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PREFACE 


Preface 


This book is a reference manual for the 
p-System . It describes the p-System facilities 
which enable you to develop programs. It is 
designed for a data processing professional who 
is familiar with the p-System. The details of 
the various programming languages—UCSD Pascal , 
FORTRAN, and BASIC—aren't covered in this 
manual. 


The following books and manuals may also be of 
interest to you. They are available from 
SofTech Microsystems. 


Personal Computing with the UCSD p-System 
UCSD Pascal Handbook 

Operating System Reference Manual 
Assembler Reference Manual 

Optional Products Reference Manual 
Internal Architecture Reference Manual 
Adaptable System Installation Manual 
FORTRAN—77 Reference Manual 

BASIC Reference Manual 
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CHAPTER 1 


INTRODUCTION 


Introduction 


HOW TO USE THIS MANUAL 


This book is a reference manual for use with the 
p-System. It describes the p-System facilities 
which enable you to develop progranms. 


Chapter 2, "Compiling Programs," covers the 
Pascal compiler. The UCSD Pascal programming 
language isn't covered in this manual. You 
should see the UCSD Pascal Handbook if you are 
interested in a thorough description of the 
language. This chapter also describes units, 
segments, and libraries. These facilities are 
used when you separately compile program 
modules. Using them you can compile and run 
much larger programs. than you would otherwise be 
able to within a given computer's memory and 
disk space limitations. 


Chapter 3, "User Interfacing," describes several 
p-System facilities that can assist your 
programs im presenting a clean and portable user 
interface. For example, the p-System can be 
completely hiddem underneath your application's 
own environment. Programs may be chained 
together and called from a simple menu driver 
that appears whem a disk is  bootstrapped. 
Whether or not. you use this approach, you may 
wish to take advantage of screen handling and 
error imterception facilities described in this 
chapter.. 
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Chapter 4, "File Management," covers the file 
management units. These allow your programs to 
manipulate disk files in a similar fashion to 
the filer. For example, files can be listed and 
removed, volumes can be crunched, and so forth. 


Chapter 5, "Debugging and Analysis" covers the 
debugger and the performance monitor units. The 
debugger is a very powerful tool for finding and 
correcting errors that might exist in programs 
you write. The performance monitor allows you 
to accumulate statistical information concerning 
various performance-related issues. Many of the 
utilities described in Chapter 6 are also 
valuable as debugging and analysis aids. 


Chapter 6, "Utility Programs," describes several 
p-System utility programs that are generally 
useful. Most of these are specifically valuable 
during program development. 


BACKGROUND 


In June 1979, SofTech Microsystems in San Diego, 
began to license, support, maintain, and develop 
the p-System. The resulting effort to build the 
world's best small computer environment for 
executing and developing applications has 
dramatically increased the growth and use of the 
p-System. The first p-—System ran on a 16-bit 
microprocessor. Today, the p-—System runs on 
8—-bit, 16-bit, and 32-bit machines—including 
the Z80, 8080/8085, 8086, 6502, 6809, 68000, 
9900, PDP-11, LSI-11, and VAX. 
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The p-System began as the solution to a problem. 
The University of California at San Diego needed 
interactive access to a high-level language for 
a computer science course. In late 1974, 
Kenneth L. Bowles began directing the 
development of the solution to that problem: 
the p-System. He played a principal role in the 
early development of the software. 


In the summer of 1977, a few off-campus users 
began running a version of the p-System on a 
PDP-11. When a version for the 8080 and the Z80 
began operating in early 1978, outside interest 
increased until a description of the p-—System in 
Byte Magazine drew over a thousand inquiries. 


As interest grew, the demand for the p-—System 
couldn't be met within the available resources 
of the project. SofTech Microsystems was chosen 
to support and develop the p-System because of 
its reputation for quality, high technology, and 
language design and implementations. 


Introduction 


DESIGN PHILOSOPHY 


The development team, many of whom continued 
their efforts on behalf of the system at SofTech 
Microsystems, decided to use _ stand-alone, 
personal computers as the hardware foundation 
for the p-System rather than large, time-sharing 
computers. They chose Pascal for the 
programming language because it could serve in 
two capacities: the language for the course and 
the system software implementation language. 


The development team had three primary design 
concerns: 


1. The user interface must be oriented 
specifically to the novice, but mst be 
acceptable to the expert. 


2. The implementation must fit into personal, 
stand-alone machines (64K bytes of memory, 
standard floppy disks, and a CRT terminal). 


3. The implementation must provide a portable 
software environment where code files 
(including the operating system) could be 
moved intact to a new microcomputer. In this 
way, application programs written for one 
microcomputer could run on another 
microcomputer without recompilation. 


The current design philosophy at SofTech 
Microsystems, where the p-—System continues to 
evolve, is bascially the same as the original 
philosophy. 
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User—Friendly 


The p-System continuously identifies its 
current mode and the options available to you 
in that mode. This is accomplished by using 
menus, displays, and prompts. You may select 
an option from a menu by pressing a 
single-character activity. The system's 
displays then guide your interactions with the 
computer. As you gain more experience, you 
can ignore the continuous status 
information—unless it is needed. 


Portability 


The p-System is more portable than any other 
microcomputer system. It protects your 
software investments without restricting 
hardware options. The p-System does this by 
compiling programs into p-code-rather than 
native machine language—thus, allowing these 
code files to be executed on any microcomputer 
that runs the p-System. 


CHAPTER 2 


COMPILING PROGRAMS 


AND UNITS 


Compiling Programs and Units 


INTRODUCTION 


This chapter is principally concerned with the 
UCSD Pascal compiler. The BASIC and FORTRAN 
compilers are described in separate reference 
manuals. However, this chapter should be useful 
even if you are only planning to use BASIC or 
FORTRAN. | 


The UCSD Pascal programming language isn't 
covered here. If you're interested in a 
detailed description of UCSD Pascal, you should 
consult the UCSD Pascal Handbook. 


separate compilation is also covered in this 
chapter. Specifically, the UCSD Pascal unit 
construct, program segmentation, and code file 
libraries are addressed. 


USING THE COMPILER 


The compiler takes a text file as input and 
generates a machine-portable code file as 
output. The generated code file contains 
p-code, which is executed by the p-System's 
p-machine emulator. This emulator is written in 
assembly language and runs directly on the host 
computer's hardware. 
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You can start the compiler by selecting the 
Ccompile or Run activity of the Command menu. 
If a work file exists, it is compiled. 
Otherwise, you are prompted for a text file to 
compile, like this: 





Enter the name of the text file, but don't 
include the ".TEXT" suffix (which is assumed). 
Next, you are asked: 


Here, you should enter the name of the code file 
that you want the compiler to produce. Don 't 
include the ".CODE" suffix (which, once again, 
is assumed). If you enter '$'! followed by 
<return>, the code file is given the name which 
corresponds to the text file being compiled. If 
you Simply press <return>, the code file 
*SYSTEM.WRK.CODE is produced. The next prompt 
is: 





Output file for compiled Listing ? (<esc> for none) 
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This allows you to indicate where you want the 
compiled listing to be sent. You can respond 
with a file name, with a communications volume 
such as PRINTER: or CONSOLE:, or simply with 
<return>. When you enter a file name, the 
listing is placed in the file. You may use the 
suffix ".TEXT", but it is always appended if you 
don't. If you specify a communications volume, 
the listing is sent there (where it is printed, 
displayed, or transmitted). When you simply 
press <return>, no listing is produced. 


The $L Pascal compiler option can also create a 
compiled listing, as described later in this 


chapter. If you indicate a file or 
communications volume in response to this 
prompt, however, the compiler option is 


overriden. (You should note that ".TEXT' isn't 
automatically appended with the $L optior as it 
is with this prompt.) 


While the compiler is running, it displays a 
report of its progress on the screen in this 


manner : 
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During the first pass, the compiler displays the 
name of each routine. In this example, 
INITIALI, AROUTINE, and MYPROG are the routines. 
The numbers enclosed within angle brackets, < >, 
are the current line numbers, and each dot on 
the screen represents one source line compiled. 


During the second pass, the names displayed are 
segments. In the example, MYPROG is the program 
segment, and INITIALI is a segment routine. 
Here the dots represent one routine within the 
segment. MYPROG contains both itself and 
AROUTINE. 


You can suppress this output if you want by 
using the $Q compiler option, described later. 


If the compilation is successful, that is, if no 
compilation errors are detected, the compiler 
creates a code file. This file is called 
*SYSTEM.WRK.CODE if you are using work files or 
if you press <return> in response to. the 
compiler's prompt: 





Otherwise, it is given the name that you specify 
in response to that prompt. 


When you select R(un (instead of C(ompile), the 
resulting code file is automatically executed. 
If you have a work code file, or if you have 
just compiled a program, R(un simply executes 
es 
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Syntax Errors 


If your program text doesn't conform to the 
rules of the Pascal programming language, the 
compiler issues a syntax error. When this 
happens, the text where the error occurred is 
displayed, along with an error number or 
message. Here are two examples: 





This is the same error displayed twice (the 
first line of a program is incorrect). In the 
first case, the error message is displayed. 
In the second case, the error number is 
displayed. You only receive the error message 
if the file *SYSTEM.SYNTAX is available. If 
*SYSTEM.SYNTAX isn't present, you need to look 
up the error number in the appropriate 
appendix to this manual. (Compiler error 
messages are given for Pascal, BASIC, and 
FORTRAN. ) 


After each syntax error, a message like one of 
these is displayed and the compiler gives you 
the option of pressing <space> to continue the 
compilation, <ese> to terminate it, or 'E' to 
enter the editor. 
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You can press <space> for every syntax error 
in the program if you wish. In this way, you 
can usually discover all of the errors that 
exist. (However, some syntax errors can 
"confuse" the compiler and hide other syntax 
errors. ) A code file is never produced if 
syntax errors are found. But, a compiled 
listing can be produced. You can use such a 
listing to keep track of the errors so that 
you can correct them all at once. 


If you elect to press ‘E' after a syntax 
error, the compilation is terminated (as it is 
with <esc>). However, you can now fix the 
error immediately because the editor 1s 
automatically invoked. If the file that you 
are compiling is a work file, it is read into 
your work space. If it isn't a work file, you 
are asked to specify which file you want to 
edit (in the editor's normal fashion). In 
either case, when the file is read into the 
work space, the cursor is placed at the exact 
spot where the error was detected. The error 
message or number is redisplayed and you must 
press <space> to begin editing so that you can 
fix the problem. When a syntax error occurs 
in an include file (see the $1 compiler 
option), you must be sure to specify that file 
correctly as you enter the editor. You are 
informed of the name of the include file after 
the "Line #" portion of the syntax error 
message. 
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If both the $Q and $L compiler options are in 
effect, the compilation continues and the 
syntax error is only reported in the listing 
file. In this case, the screen remains 
undisturbed by syntax errors. 


Compiled Listings 


The compiler may optionally produce a listing 
of the compiled source. This listing contains 
your text along with information about the 
compilation. Compiled listings are very 
useful for reference as well as analysis and 
debugging purposes. 


In order to produce a compiled listing, you 
can use the compiler's prompt for a listing 
file which is described above. Alternatively, 
you can use the $L compiler option which is 
described under compiler options, below. 


Here is the entire compiled listing for a very 
Simple program: 
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Here is a sample portion of a more complex 
listing: 
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In those lines that aren't marked as commented 
out (which is intended to warn you that a 
comment may have accidentally eliminated some 
Pascal code), the numbers that precede a 
source line are: 


1. The line number. For example, 397 in the 
listing above. 


2. The Pascal segment number. This entire 
example is part of segment number 10. 


3. The routine number followed by a colon and 


the "lex level." In the example, procedure 
iocheck is routine number 12 and procedure 
dropindex is routine 13. The lex level 


indicates how deeply the text is nested 
within Pascal begin-end pairs. 


4. The number of bytes of data or code storage 
which the routine requires at that point. 
For example, the IF statement, line 399, 
requires 6 bytes of p-code. The entire 
procedure iocheck requires 50 bytes of 
p-code. 


Lines which contain declarations (variables, 
constants, and so forth) show a "d" following 
the routine number. In the listing above, 
lines 393 and 397 are examples of this. 
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When the module that you are compiling uses a 
unit, the interface section of that unit 
appears in the compiled listing with a "u" 
where the "d" normally appears. Also, the 
additional line 'USING <UNITNAME>' appears in 
the heading to make it easier for you to 
distinguish interface sctions from the text 
that you are specifically compiling. 


Here is a portion of a compiled listing which 
shows syntax errors: 





This shows two instances of error 104. This 
particular error indicates that an undeclared 
identifier was found—"lastpageitem" is the 
problem in both cases. An actual message 
indicating "undeclared identifier" would have 
been listed if the file *SYSTEM.SYNTAX had 
been available. 


Error messages indicate the position of the 
previous syntax error. In this example, line 
096 contains the first syntax error and line 
602, which contains the second, references 
line 596 as the previous syntax error. 
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Compiler Options 


You may direct some of the compiler'’s actions 
by the use of compiler options embedded in the 
source code. Compiler options are a set of 
commands that may appear within 
"pseudo-comments." A pseudo-comment is like 
any other Pascal comment (it is surrounded by 
'(*' and '*)', or by '{' and '}'). However, a 
dollar sign immediately follows the left-hand 
delimiter, for example: 





There are two kinds of compiler’ options: 


"Switch" options and "string" options. A 
switch option is a letter followed by a 't'’, 
i", Orem, A string option is a letter 


followed by a string. (In the examples above, 
the second is a string option; the others are 
switch options.) A pseudo-comment may contain 
any number of switch options (separated by 
commas), and zero or one string options. If a 
string option is present in a pseudo-comment, 
it must be the last option. The string is 
delimited by the option letter and the end of 
the comment. 


If the pseudo-comment uses ‘'(*' and '*)', the 


string in a string option may not contain an 
te! 
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some options may appear anywhere within the 
source text. Others must appear at the 
beginning of the file (before the reserved 
word PROGRAM or UNIT). 


Switch options are either toggles or stack 
options. If a switch option is a toggle, a 
'+' turns it on, anda '—' turns it off. The 
options 'I' and 'R' are "stack options," as 
are the conditional compilation flags (see 
below). 


With each stack option, the current state 
(either '+' or '-') is saved on the top of a 
stack (up to 15 states deep). The stack may 
be "popped" by a ‘'*' (thus re-~enabling the 
previous state of that option). If the stack 
is "pushed" deeper than 15 states, the bottom 
state of the stack is lost. If the stack is 
popped when it is empty, the value is always 
' t 
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The individual compiler options are described 
below in alphabetical order. If you don't use 
any compiler options, their default values 
will be in effect. Here are the default 
values for the compiler options: 
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These remain in effect unless you override 
them. 


The $Q option defaults to Q if HAS SLOW 
TERMINAL is false and Q@+ if HAS SLOW TERMINAL 
is true. (HAS SLOW TERMINAL is a data item in 
SYSTEM.MISCINFO which indicates whether or not 
you have a hard copy terminal or a screen). 


Conditional compilation is also controlled by 
compile-time options as described below. 


$B — Begin Conditional Compilation 


$B is a string option. It starts 
compilations of a section of conditionally 
compiled source code. See the section on 
conditional compilation, below. 


$C — Copyright Field 


$C is a string option. It places the string 
directly into the copyright field of the 
code file's segment dictionary. The purpose 
of this is to have a copyright notice 
embedded in the code file. 
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$D — Conditional Compilation Flag 


$D is a string option. It is used to 
declare or alter the value of a conditional 
compilation flag. See the section on 


conditional compilation, below. 


$D — Symbolic Debugging 


There are two $D compiler options. This one 
is a switch option. $D+ turns on symbolic 
debugging information. $D- turns off 
symbolic debugging information. The default 
is $D-. (See Chapter 5 for more informaton 
about this compiler option. ) 


$E — End Conditional Compilation 


"BE" is a string option. It ends a section 
of conditionally compiled source code. 


$I — I/O Check Option 


There are two options named by $l. The 
first is a stack switch option (IOCHECK). 


$I+, which is the default, instructs the 
compiler to generate code after each [/0 
statement in a program. This code verifies, 
at run-time, that the I/O operation was 
successful. If the operation wasn't, the 
program terminates with a run-time error. 
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$I- instructs the compiler not to generate 
any I/O checking code. In the case of an 
unsuccessful I/O operation, the program 
continues. 


When you use the $I- option, your programs 
Should specifically test IORESULT (an 
intrinsic p-System function) when there is 
the chance of an I/O failure. If $I- is 
used and you don't test IORESULT, the 
effects of an I/O error are unpredictable. 


During program development you should 
probably use $I+. When your program is 
thoroughly debugged, you may wish to use $I- 
Since less memory space is required without 
the I/O checking code. Also, you may wish 
to intercept I/O errors in your program. 
(For example, you may enter something 
incorrect from the keyboard. Rather than 
terminating with an I/O error, your program 
could prompt you to correct the problem and 
try again.) 


$I — Include File 


This is a string option. The string 
(delimited by the letter ‘'I' and the end of 
the comment) is interpreted as the name of a 
file. If that file can be found, it is 
included in the source file and compiled. 
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This includes the file PROG2.TEXT in the 
program's source. 


If the initial attempt to open the include 
file fails, the compiler concatenates 
"TEXT" to the file name and tries again. 
If this second attempt fails, or an [I/O 
error occurs while reading the include file, 
the compiler responds with a fatal syntax 
error. 


In order that included source may carry its 
own declarations, an include file may 
contain CONST, TYPE, and VAR declarations, 
optionally followed by routine declarations. 
If this is the case, then the {$I...} 
comment must precede any routine 
declarations in the main program. 
Otherwise, the include file must follow 
normal Pascal ordering. 





Include files may be nested up to three 
files deep (but no deeper). 


Note that if a file name begins with a 't' 
or '-—', a blank must be inserted between the 
letter 'I' and the string. For example: 
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$L — Compiled Listing 


You may use $L either as a toggle switch 
option or a string option. When uSed as a 
toggle, it turns the listing on or off at 
that point in the source text. When used as 
a string option, it indicates the name of 
the listing file. 


Here are two examples of $L with a string 
option: 





The first example indicates that the 
compiled listing is to be saved on disk as 
the file LIST.TEXT. The second example 
sends the listing to the printer. 


When used as a toggle, $L+ turns the listing 
on and §$L-turns it off. Using these 
options, you can list only parts of a 
compilation if you wish. The default for 
the toggle is $L- if you have not named a 
listing file using the compiler'’s prompt or 
using $L with a string option. The default 
is $L4+ if you have named a listing file in 
either of these ways. No matter which way 
you name the listing file, you can switch 
the listing on or off using $L+ or $L-. 
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If you don't specifically name a listing 
file and $l+ is in effect, the compiler 
writes to *SYSTEM.LST.TEXT. 


You should note that listing files which are 
sent to disk files may he edited as any 
other text file, provided they are created 
with a .TEXT suffix. Without the .TEXT 
suffix, the p-System treats the listing as a 
data file. With the $L option, .TEXT is 
never appended. However, from. the 
compiler'’s prompt for a listing file, .TEXT 
is always appended (unless you enter it 
specifically). 


$N — Native Code Generation 


This is a swtich option. $N+ outputs 
compiler information which allows code 
generation to take place. $N— doesn't 
output this information. The default is 


$N-. This option is discussed in the Native 
Code Generator section which is part of the 
Optional Products Reference Manual. 


$P — Page and Pagination 


The compiler can place page breaks in the 
compiled listing. It does this so that 
listings sent to the printer (or listings 
sent to files and later T(ransferred to the 
printer) break across page houndaries. A 
form feed character (ASCII FF) is output 
every 66 lines if $P+ is in effect (this is 
the default). If you don't want this, you 
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should use $P-. 


You can specifically cause a page break at 
any point in a compiled listing by using the 
$P option without a plus or minus sign. 


$Q — Quiet 


This is used to suppress the compiler's 
standard output to the console. $Q+ causes 
the compiler to suppress this output and $Q- 
causes it to resume outputting status 
information. 


$R — Range Checking 


$R is a stack switch option. The default, 
$R+, causes the compiler to output code 
after every indexed access (for example, to 
Pascal arrays) to check that it is within 
the correct range. This is called range 
checking. $R- turns range checking off. 


Programs compiled with the $R- are slightly 
smaller and faster since they require less 
code. However, if an invalid index occurs 
or a invalid assignment is made, the program 
isn't terminated with a run-time error. 
Until a program has been completely tested, 
it is suggested that you compile with the Rt 
option left on. 
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$R2 and $R4 —- Real Size 


$R2 causes the code file's floating point 
arithmetic operations to be performed with 
two word (32-bit) precision. $R4 causes 
four word (64-bit) precision. The default 
real size depends upon the particular PME 
that you are using (that is, if your PME 
runs four word reals, the default is four 
words ). This directive must occur before 
the first symbol in a compilation that isn't 
a comment. 


NOTE: If you attempt to run a code file 
with one real size using a system configured 
for another real size, you will receive 
execution error 17 (real size mismatch). 


$T -— Title 


$T is a string option. The string becomes 
the new title of pages in the listing file. 


$U — Use Library 


There are two options indicated by $U. One 
is a string option (Use Library). The 
other, described below, is a toggle switch 
option (User Program). 
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With the Use Library option, the string is 
interpreted as a file name. This file 
Should contain the unit(s) that your program 
is about to use. If the file is found, the 
compiler attempts to locate the unit(s) that 
eG needs for the subsequent USES 


declarations. If a particular unit isn't 
found there, the compiler looks in 
*SYSTEM. LIBRARY. 


If a client (program or unit) contains USES 
declarations but no $U option, the compiler 
looks for the used units first in the source 
file itself, and then in *SYSTEM.LIBRARY. 


The following is an example of a valid USES 
clause using the $U option: 





$U - User Program 


This option is used to specify whether the 
compilation is your compilation, or a 
p-System compilation. If present, it must 
appear before the heading (that is, before 
the reserved word PROGRAM or UNIT). 
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When the default $U+ is in effect, your 
program is indicated. The $U— option allows 
system programmers to compile units with 
names that are predeclared in the p-—System. 
These units are actually part of the 
p-System, itself. $U- also sets $R- and 


[-. 


In general you should never use this option, 
unless you need to compile GOTOXY (See the 


Adaptable System Installation Manual). 





Conditional Compilation 


You may conditionally compile portions of the 
source text. At the beginning of a program's 
text you can set a compile-time flag which 
determines whether or not the conditionally 
compiled text will be compiled. 


In order to designate a section of text as 
conditionally compilable, you must delimit it 
by the options $B (for begin) and $E (for 
end). Both of these options must name the 
flag which determines whether the code between 
them is compiled. The flag itself is declared 
by a $D option at the beginning of the source. 
$D options may be used at other locations in 
the source to change the value of an existing 
flag. 
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Here is an example: 





Each flag in a program must appear in a §$D 
option before the source heading. The name of 
a flag follows the rules for Pascal 
identifiers. If the flag's name is followed 
by a '—', that flag is set false. The flag 
may be followed by a '+', which sets it true. 
If no Sign is present, a flag is true. The 
flag's name may also be followed by a '*' as 
Shown below. 


The state of a flag may be changed by a $D 
option which appears after the source heading, 
but the flag must have first been declared 
before the heading. 
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The $B and $E options delimit a section of 
code to be conditionally compiled. The $B 
option may follow the flag's name with a '-', 
which causes the delimited code to be compiled 
if the flag is false. In the absence of a 
'-', the code is compiled if the flag is true. 
The flag's name may also be followed by a '+' 
or '*'; these are ignored. In a $E option, 
the flag's name may be followed by a 't', '-', 
or '*'; these symbols are ignored. 


The state of each flag is saved in a stack, 
just as the state of a stack switch option is 
saved. Thus, using a $D option with ‘7! 
yields the previous value of the flag. KEach 
flag's stack may be as many as 15 values deep. 
If a 16th value is pushed, the bottom of the 
stack is lost. If an empty stack is popped 
with '*', the value returned is always false. 


If a section of code isn't compiled, any 
pseudo—-comments it may contain are ignored as 
well. 
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Selective Uses 


Selective uses allows your programs to choose 
the items that you wish to use from a unit's 
interface section. You can often take 
advantage of this to reduce compile-time space 
requirements. Also, compilation time can be 
reduced. Both of these are especially 
noticeable when you are using units with large 
interface sections from which you only require 
a few items. This is because the rest of the 
interface section doesn't need to be compiled. 


Also, selective uses is valuable for 
documentation purposes in that you can easily 
See the specific items that a client needs 
from the unit it uses. 


The following diagram explains the syntax of 
selective uses: 


unit 
identifier 





In this diagram, ident can be a constant, 
type, variable, or routine (procedure, 
process, or function). Here is an example of 
a Screen uses Se 


. oo. om om 7t 


a ay 
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If a selected declaration isn't present in the 
interface text, an error results during 
compilation. 


Any constant or type used in a_e selected 
declaration must be included in the selective 
uses list. For example, if VAR] is of type 
TYPE1, the list above isn't acceptable unless 
TYPE] is added (even though TYPE] may not be 
directly required by the client being 
compiled). 


You Should list only the name of a routine. 
No explicit listing of parameters is needed. 
However, any types or constants that the 
parameters use must be explicitly included. 


Most identifiers must be named explicitly in 
the identifier list if they are to be made 
available to the compiled module. Identifiers 
are available implicitly in these situations: 


@ When an enumerated constant type is 
explicitly listed, all the constant 
identifiers of the enumeration are 
implicitly available. 


@ When a record type is explicitly listed, 
all its field names are implicitly 
available (for example, see the following 
listing under unit A, line 12, info rec). 
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Here is an example of selective uses. Unit A 
is selectively used by Units B and C. 


Unit A; 

interface 

const 
maxnum=1000; 
maxchar=7; 


type 
byte=0..255; 
codeblock=packed array 
CO..maxnum] of byte; 
atpha=packed array 
CO..maxchar] of char; 
ptr info rec= info rec; 
info _rec=record 
code:codeblock; 
Llink,rlink:ptr_info rec; 
end; 
next=char; 


var 
first,last:byte; 


function update(var info:ptr_info_ rec) 
mnext; 


implementation 


function update; 
begin . 
with info do 
begin 
Llink:=rlink; 
if rlink=Llink then 
update:="y" | 
else 
update:='n'; 
* end; 
end; 


end. Cunit A} 
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Unit B>. . 

interface 

{$U a.code} — 

uses a(€ {const} maxchar, 
{include for type ALPHA} 

. {types} alpha, 
{include for variable WHICH} 
ee byte, 

- Cinclude: for FIRST and LAST} 
“ {vars } first, 
{include for proc CHANGE} 

Es last 
{include for proc CHANGE} 


sing A 


maxchar=7 ; 
byte=0..255; 
alpha=packed array 
*-£O..maxchar] of char; 
_first,last:byte; 

Ne 


procedure change<which:alpha) ;: 
implementation 


. procedure change; 
begin . 
if which=' " then 
Last:=first 
else 
first:=Last; | 
end; 


end; {unit B} 
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Unit C; 

interface 

' implementation - 

{$U a.code} . 

uses aC. {const} .maxnum, 


. {include for type CODEBLOCK} 


maxchar, 
Cinclude for type ALPHA} 
oe byte, 


‘Linclude for type CODEBLOCK} 


- <type} . alpha, — 
{include.for variable MINE} 
, ie Sanfolrec, * 
Cinclude for PTR. INFO_ REC} 


ptr info - rec, 


_ {include for. func UPDATE} 
“ads codeblock, 
Cinclude for INFO REC} 
Ra Peg next, 
{include for func UPDATE} 
sing A... irs 
maxnum=1000; 
maxchar=7; 
byte=0..255;. ; 
codeblock=packed array. 
C0...maxnum] of byte;- 
alpha=packed array 
CO..maxchar] of char; 
ptr.. info _ rec= 
info. rec=record 
_code: codeblock; 
Llink,rlink: i= info 
; “end; 
next= =char; ~ 
_ function update 


_ info rec; 


rece 


var info:ptr_ info rec): next}. 


ae €func} update), 
- Using B- 


“var 
infozptr. info rec; 
minezalpha; 

bela. 
newCinfo):” 
newCinfo - 
info , 
- minez="newsystm'; -- 


Sf update(info)="y' then 


writeln(' info updated?) 
else ie 
change(mine) ; 

end. : 


“artink);. 
-llinks= =nily. 
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SEGMENTS, UNITS AND LIBRARIES 


segments, units, and libraries are three major 
facilities that help you manage large programs 
and effectively use main memory. These 
facilities enable very large programs to be 
developed in a microsystem environment; in fact, 
these facilities were used extensively in 
developing the system, itself. 


Segmenting a Program 


An entire program need not to be in main 
memory at run-time. Most programs can be 
described in terms of a working set of code 
that is required over a given time period. 
For most—if not all—of a program's execution 
time, the working set is a subset of the 
entire program, sometimes a very small subset. 
Portions of a program that aren't part of the 
working set can reside on disk, thus freeing 
main memory for other uses. 


When the p-System executes a code file, it 
reads code into main memory. When the code 
has finished running, or the space it occupies 
is needed for some action having higher 
priority, the space it occupies may be 
overwritten with new code or new data. Code 
is swapped into main memory a segment at a 
time. 
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In its simplest form, a code segment includes 
a main program and all of its routines. A 
routine may occupy a segment of its own; this 
is accomplished by declaring it a segment 
routine. Segment routines may be swapped 
independently of the main program; declaring a 
routine a segment is useful in managing main 
memory . 


Routines that aren't part of a program's main 
working set are prime candidates for occupying 
their own segment. Such routines include 
initialization and wrap-up procedures’ and 
routines that are used only once or only 
rarely while a program is executing. Reading 
a procedure in from disk before it is executed 
takes time. Therefore, the way that you 
divide up a program is important. 


UCSD Pascal, FORTRAN, and BASIC use their own 
syntax for creating separate segments. Refer 
to each particular language's manual for more 
information on this. 


Separate Compilation — Units 


Separate compilation is a technique whereby 
segments of a program are compiled separately 
and subsequently executed as a coordinated 
whole. 
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Many programs are too large to compile within 
the memory confines of a particular 
microcomputer. Such programs might 
comfortably run on the same _ machine, 
especially if they are segmented properly. 
Compiling small pieces of a program separately 
can overcome this memory problem. 


Separate compilation also allows small 
portions of a program to be changed without 
necessarily affecting the rest of the code. 
This saves time and is less error. prone. 
Libraries of correct routines may be built up 
and used in developing other programs. This 
capability is important if a large program is 
being developed and is invaluable if the 
project involves several programmers. 


These considerations also apply to assembly 
language programs. Large assembly programs 
(such as p-machine emulators) can often be 
more effectively maintained in several 
Separate pieces. When all these pieces have 
been assembled, the L(inker puts them together 
and installs the linkages that allow the 
various pieces to reference each other and 
function as a unified whole. 


You may also want to reference an assembly 
language routine from a higher-level language 
host program; for example, Pascal or FORTRAN. 
This may be necessary for performance reasons 
(assembly language is faster than p-code, the 
output of the compilers) or to provide 
low-level, machine-dependent or 
device-dependent handling. 
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Using the L(inker, the p-System allows 
assembly language routines to be linked with 
other assembly routines or into higher-level 
clients (programs or units). For more 
information about this, see the Assembler 
Reference Manual. 


In UCSD Pascal, separate compilation is 
achieved by the unit construct—a unit being a 
group of routines and data structures. The 
contents of a unit usually relate to some 
common application, such as screen control or 
data file handling. A program or another unit 
may use the routines and data structures of a 
unit by simply naming it in a USES 
declaration. The term "host" refers to such a 


program, and "client compilation module" 
refers to a program or unit that uses another 
unit. In addition to being a separately 


compiled module, a unit is also a code 
segment, in that it can be swapped—as a 
whole—in and out of memory. You should note 
that it is possible for a unit's source text 
to be embedded in the client's source text if 
you don't want to compile a unit separately. 


A unit consists of two main parts: (1). the 
interface section, which can declare 
constants, types, variables, procedures , 
processes, and functions which are public 
(available to any client module); and (2) the 
implementation section, in which private 
declarations can be made. These private 
declarations are available only within the 
unit and not to client modules. 
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Pascal, BASIC, and FORTRAN use their own 
syntax for separate compilation. (For more 
information about this, refer to each 
language's manual.) 


Libraries 


This section describes where you may place the 
code files that contain units so those units 
are available at compile-time or run-time. 
Run-time availability is described first. 


There are four places where units may reside 
when the client's code is executed: 


1. Within the client's code file. 
2. In the SYSTEM.LIBRARY on the system disk. 
3. In a user library. 


4. In the operating system (SYSTEM.PASCAL). 


The operating system units (described in the 
next chapter) are standard code. Don't place 
units that you write there. The other three 
options are available for units that you write 
or use. 
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In order to place a unit directly into a 
client's code file, use the Jibrary utility, 
described in Chapter 6. Once the unit's code 
and the client's code are unified like this, 
the unit 18 available at run-time. 


SYSTEM.LIBRARY generally contains standard 
units, such as the long integer package. You 
can add your units to this file with the 
Library utility. If you aren't currently 
using SYSTEM.I,IBRARY, you can simply rename a 
unit's code file "SYSTEM.LIBRARY" and place it 
on the boot disk. Of course, you can add more 
files with the Library utility. All units 
that reside in SYSTEM.LIBRARY are available to 
clients. 


A user library is any code file. The name of 
this code file must be in a "library text 
file." The standard default library text file 
is called USERLIB.TEXT and must be on the 
system disk. For example, if you create a 
USERLIB.TEXT containing these lines: 





These three code files are designated as user 
libraries. You don't have to specify the 
",CODE" here. For example, the first file may 
be either DISK2:SOME.UNITS.CODE or 
DISK2:SOME.UNITS, depending upon which file is 
actually found. All three of these files may 
contain units which are then available for you 
to use. 
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When the p-System is searching several 
libraries for a unit, it first searches all of 
the user libraries in the order that they 
appear in the default library text file. It 
then searches *SYSTEM.LIBRARY. If you wish to 
include *SYSTEM.LIBRARY in the library text 
file, it 1S searched in the order that it 
appears. (If no library text file is used, 
only *SYSTEM.LIBRARY is searched. ) 


You can use a library text file, other then 
USERLIB.TEXT. Do this with the 'L' execution 
option. For example, if you select X(ecute 
from the Command menu and respond: 





During compile-time, as opposed to run-time, 
the code for a unit may reside in either of 
two locations: 

1. *SYSTEM. LIBRARY 


2. A code file specified in the text you are 
compiling. 
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Pascal, BASIC, and FORTRAN each have a way to 
indicate the names of units that are to be 
used. hach language also has a method for 
specifying the code files that contain those 
units. If you don't indicate a particular 
code file, the compilers search 
*SYSTEM.LIBRARY for any units you want to use. 
If you do indicate a code file, the compilers 
look there for the units. You can specify one 
unit as being in a particular code file, and 
another unit as being in a different code file 
if you wish. 
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GENERAL TACTICS 


This section describes the use of segments and 
units. It presents a scenario for designing a 
large program, with some useful strategies. 


Units and segments divide large programs into 
independent tasks. On microprocessor systems, 
the main bottlenecks in developing large 
programs are: 


@ A large number of variable declarations that 
consume space while a program is compiling. 


@ Large pieces of code that use up memory space 
while the program is executing. 


Units address the first problem by: (1) 
allowing separate compilation; and (2) 
minimizing the number of variables needed to 
communicate between separate tasks. Segments 


alleviate the second problem by only requiring 
code that is in use to be in main memory at any 
given time; during this time, unused code 
resides on disk. 


You can write a program with run-time memory 
management and separate compilations already 
planned, or you can write as a whole and then 
break it into segments and units. The latter 
approach is feasible when you're unsure about 
having to use segments or quite sure that they 
will be used only rarely. The former approach 
is preferred and easier to accomplish. 
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The following steps outline a typical procedure 
for constructing a relatively large application 
program: 


1. Design the program (user and machine 
interfaces). 


2. Determine needed additions to the library of 
units, both general and applied tools. 


3. Write and debug units and add to libraries. 
4. Code and debug the program. 


Oo. Tune the program for better performance. 


During design, try to use existing procedures to 
decrease coding time and increase reliability. 
You can accomplish this strategy by using units. 


To determine segmentation, consider the expected 
execution sequence and try to group routines 
inside segments so that the segment routines are 
called as infrequently as possible. 


While designing the program, consider’ the 
logical (functional) grouping of procedures into 
units. Besides making the compilation of a 
large program possible, this can help the 
program's conceptual design and make testing 
easier. 
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Units may contain segment routines within them. 
You should be aware that a unit occupies a 
segment of its own; except, possibly, for any 
segment routines it may contain. The unit's 
Segment, like other code segments, remains 
disk-resident except when its routines are being 
called. 


Steps 2 and 3 of the typical construction 
procedure are aimed at capturing some of the new 
routines in a form that allows them to be used 
in future programs. At this point, you should 
review, and perhaps modify, the design to 
identify those routines that may be useful in 
the future. In addition, useful routines might 
be made more general and put into libraries. 


Program and test the Library routines before 
moving on to programming the rest of the 
program. This adds more generally useful 
procedures to the library. 


The interface part of a unit should be completed 
before the implementation part, especially if 
several programmers are working on the same 
project. 


Tuning a program usually involves performance 
Tuning. Since segments offer greater memory 
space at reduced speed, performance is improved 
by: (1) turning routines into segment 
routines; or (2) turning segment routines back 
into normal routines. Either route is feasible. 
Pay some attention to the rules for declaring 
segments. 
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For information on languages, refer to. the 
appropriate language manual. 
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USER INTERFACE 


User Interface 


INTRODUCTION 


This chapter describes several facilities that 
can assist you in presenting a clean and 
portable user interface from your programs. 


The first section describes run-time facilities 
that enable you to create your own applications 
environment. The p-System can run invisibly 
under your application using these facilities. 


The next section describes the screen control 
unit. This unit, which is part of the operating 
system, can be used by your programs to easily 
handle the basic screen-oriented functions (such 
as clearing the screen, moving the cursor, and 
so forth). 


Next, the error handler unit is covered. It 
enables your programs to intercept certain kinds 
of system errors and display your own messages. 
You might want to do this so that the error 
messages are specific to your particular 
application, or they are in a different 
language, and so forth. 


After this, the command I/O unit is described. 
This unit allows you to redirect I/O and chain 
programs together. It is especially useful in 
conjunction with the run-time facilities in the 
first section. 
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RUN-TIME APPLICATION FACILITIES 


As an applications developer, you may create 
programs which are automatically executed by the 
p-System. This exempts the end user from having 
to X(ecute these programs. The underlying 
p-System can even be completely hidden from such 
a user. You may present menus and prompts that 
apply specifically to your particular 
application. 


If you name an executable code file, 
SYSTEM. STARTUP, and place it on the system disk, 
that program is executed when the p-System is 
booted. This program begins before the 
p-System's Command menu or welcome message is 
displayed. 


SYSTEM.MENU operates similarly. It is executed 
each time the Command menu would normally be 
displayed. 


Generally, SYSTEM.MENU is more useful for 
creating your own applications environments 
Since it is called up repeatedly. Typically, 
you might place a simple menu-driven program in 
SYSTEM.MENU. This program displays the outer 
menuS or prompts and services global issues 
related to your application package. When you 
select a component of your package, you would 
use the CHAIN procedure (within the operating 
system's Command I/O unit, described later in 
this chapter). CHAIN allows another program to 
be executed (without using the X(ecute command 
or displaying the Command menu in between). 
When that program completes its run, SYSTEM.MENU 
is again called. In this sort of scenario, the 
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p-System's Command menu never appears. 


Single—Use Run-Time System 


The run-time system is a version of the 
p-System designed to package and execute a 
Single application program or series of 
related programs called by the p-System chain 
mechanism just described. This version of the 
p-System never reaches the Command menu. The 
p-System components, such as the editor and 
filer, aren't a part of this package. The 
package may contain SYSTEM.STARTUP, but must 
contain SYSTEM.MENU. 
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System Initialization 


The following diagram illustrates the. flow of 
control each time the p-System is initielized: 


SYSTEM INITIALIZATION 





EXECUTE *SYSTEM. STARTUP 
(IF POSSIBLE) 






IS CHAIN OF PROGRAMS. ————— NO 


EMPTY? 





YES EXECUTE CHAINED 
PROGRAM 


iS *SYSTEM. MENU. ———--—————»_ YE 





EXECUTABLE? ; 
NO EXECUTE 
*SYSTEM.MENU 
SINGLE-USE 


TURNKEY SYSTEM?,_ —————— YES ———» HALT 


NO 


MAIN SYSTEM PROMPT 
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THE SCREEN CONTROL UNIT 


The screen control unit is a unit within the 
operating system which your programs can use to 
easily perform several useful screen-oriented 
tasks. These include blanking out a line or the 
entire screen, placing the cursor at a 
particular position, displaying p-System style 
menus, and so forth. These tasks are performed 
in a way that makes your programs transportable 
across different video displays. 


You should realize that there is a special 
screen control unit for ANSI (American National 
Standards Institute) terminals. (These 
terminals use three character sequences. Most 
other terminals use, at most, two character 
sequences. ) However, the interface section of 
this special version of the screen control unit 
is no different from the standard unit. This 
means that your programs don't have to be 
changed. 


To use the screen control unit at compile time, 
you must have a copy of SCREENOPS.CODE with its 
interface section. A Pascal program must 
contain USES declaration similar to this: 





At run-time, only the operating system needs to 
be available since it contains the SCPEENOPS 
unit (only without the interface section). 
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SCREENOPS Interface Section 


Here is a listing of the interface section for 
SCREENOPS : 


unit screenops; 
interface | 


const. _ 
sc fill_ten = 11; 
$0 3 “eol = 455 


type 

sc_chset . - °° = set of char; 

sc misc rec packed record 

height, width : 0..255; 
can_break,: slows xy crt, tc crt, 
-can "_upscrolt, can . downscrott. s boolean: 
end; s , 
sc_date rec = packed record 
month : 0..12; 
day : .0..313 
year : 0..99; 
— end; 
sc_info type = packed record 
~se_version : string; 
--$c date :-sc date rec; 
spec_char : ‘SC_ chset; {Characters not to echo} 
misc_info : sc _misc_rec; 

string[255]; 

(sc_whome, sc eras s, sc_erase eol, sc_clear_lne, 
sc_clear_sen, sc_up cursor, sc_ down cursor, 
sc_left_cursor, sc igh: cursor); 

(sc ~ backspace key, sc.dct key, sc_eof_key, sc_etx_key, 
sc_-escape key, SC del _key, sc_up | . key, sc down | key, 
sc Left key, sc _right _key, sc_not legal, sc_insert_key, 
sc delete key); 


~ sc_ tong string 
sc_scrn_command 


Nou 


sc_key_ command 


sc_choice - 


= (se | get, sc give); 
sc_window = packed array [0..0] of char; 
sc _tx_port. = record 
row, col, ._ . { screen relative} 
height, width, -  € size of export (zero based) } 
cur x, cur_sy integer; 
geukan positions relative to the. txport } 
end: : 
fentries 4..syscom -subsidstart-1 are valid} 


sc_err_msg array = array C4:.41| of. string; {accessed $R-} 
var 

sc port : sc tx. _port; 

sc printable | chars +.3¢ _ chset; 


sc_errorline : 
scerrormessage : 


‘ procedure 
procedure. 
procedure 
procedure 
procedure 
procedure 
procedure 
‘procedure 
procedure 
procedure 
procedure. 
procedure 
procedure 
procedure 
function 

function 
function. 

function. 
function 

function 


function | 


function 
procedure 
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integer; haGs Sole A i 
: _. $¢.err_msg array; 

SC. use info(do what: SC _ choices. var t_infozsc_info_type); 

$c_use " port(do_ . whatise choice; var t port: sc. tx EPnEE7 

Sc _@rase to eol (x, Line: integer); 

sc left: . =e — 

Sc “right; 

Sc_up; 

sc down; 

sc-getc_ch(var ch:char;- return on _match: Sc _chset); 

se clr screen; 

se. clr line Cy: integer); 

SC _home;. 

sc_eras eos (x, Line: integer); 


sc goto xy(x, bipae integer) ; 


Sc. ~elr cur "ine; 

SC. - find: | xrinteger; 

SC find | y: integer; 

St. sern  hastwhat: sc_scrn_ command : boolean; 

sc_| has | key (what: Sc key command) : boolean; 

sc_map crt. command(var | k chschar):s sc key _ command; 

SC prompt (Line zsc_long | string;. x _-cursor,y_ cursor ,x: pos, 
where: integer; return _on_match:sc * chset: 
no char: back:boolean; break char:char) schar; 

sc_check_ char (var. | buf:sc _Window; var buf_ index pbytes_ left: integer) 

- sboolean; 


sc _space_ wait(flush: boolean) sboolean; 


sc init; 
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Routines within SCREENOPS 


This section describes the routines within the 
screen control unit. The text ports mentioned 
here are rectangular portions of the screen 
that may be defined as smaller than the real 
screen. At present, this feature isn't fully 
implemented. Where text ports are mentioned 
in this section, the entire screen is the 
default. 


Procedure SC Init; 
Usually, only the operating system calls this 


procedure. It initializes all the screen 
control tables and variables. 


Procedure SC Clr Cur Line; 


Brases the current line. 


Procedure SC Clr Line ( Y: integer ); 


Clears line number Y within the current text 
port. 


Procedure SC Cir Screen; 


Clears the screen. 
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Procedure SC Erase to EOL 
( X, Line: integer ); 


Starting at position (X, Line) within the 


current text port, erases everything to the 
end of the line. 


Procedure SC_ Eras EOS 
( X, Line: integer ); 


Starting at position (X, Line) within the 


current text port, erases everything to the 
end of the screen. 


Procedure SC Left; 


Moves the cursor one character to the left. 


Procedure SC Right; 


Moves the cursor one character to the right. 


Procedure SC_Up; 


Moves the cursor one line up (in the same 
column). 


Procedure SC_Down,; 


Moves the cursor one line down. 
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Procedure SC_Home; 


Moves the cursor to position 0,0 within the 
current text port. 


Procedure SC_GOTO XY 
( X, Line: integer ); 


Moves the cursor to position (X, Line). 


Function SC Find X: integer; 


Returns the column position of the cursor, 
relative to the current text port. 


Funtion SC_Find Y: integer; 


Returns the row position of the cursor, 
relative to the current text port. 


Procedure SC _GetC_CH 
( VAR CH: char; 
Return on Match: SC Chset ); 


SC _ChSet is a SET OF CHAR. This procedure 
repeatedly reads from the keyboard into CH 
until CH is equal to a member of 
Return on Match. The characters that you pass 
in this set should all be capitals (if they 
are alphabetic). If a lowercase alphabetic 
character is received from the keyboard, it is 
translated into uppercase before it is 
compared to the characters within 
Return_on Match. 
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Function SC Space Wait 
( Flush: Boolean ): Boolean; 


This function repeatedly reads from the 
keyboard until a space or the ALTMODE 
character is received. Before doing this, it 
does a UNITCLEAR(1) if flush is true, and 
displays ‘Type <space> to continue'. It 
returns true if a space wasn't read. After 
reading a <space> successfully, this function 
echoes a carriage return on the console. 
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Function SC Prompt 
( Line: SC _ Long String; 
X Cursor, Y Cursor, X Pos, 
Where: integer; 
Return on Match: SC ChSet; 
No Char Back: Boolean; 
Break Char: char): char; 


This function displays the menu line 
(SC_Long String is a STRING [255]) in the 
current text port at (X Pos, Where). The 
cursor is placed at (X Cursor, Y Cursor) after 
the prompt is printed. If X Cursor is less 
than O, the cursor is placed at the end of the 
prompt. If the prompt is too large to fit 
within the current text port, it is broken up 
into several pieces, but only at _ the 
Break Char. You can view different parts of 
the prompt (cycling through them) by entering 
'?', If you only want to display the prompt, 
No Char Back should be true. In this case, 
SC Prompt returns a function value of NUL, 
ASCII 0. If you want to receive a character 
from the user at the keyboard, No Char Back 
Should be false. (In this case, SC Prompt 
returns a functon value of the character 
received. ) The keyboard is repeatedly read 
until the character read matches one within 
the Return_on Match set. This set should be 
all capitals (for alphabetic characters) since 
your input is converted to uppercase when 
necessary. 
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Function SC Check Char 
( VAR Buf: SC | Window; 
VAR Buf Index, 
Bytes Left: integer): Boolean; 


While a string is being read, this function 
may be called to see if a backspace or a 
rubout (DEL) has been read. If so, the input 
buffer is altered accordingly, and true is 
returned. Buf is a line on the screen, 
Buf Index indicates the cursor position within 
Buf, and Bytes Left is the number of 
characters to the right of the cursor. 


Function SC Map CRT Command 


( VAR K CH: char ): SC Key Command; 


SC Key Command is a type consisting of the 


following elements: SC Backspace Key, 
SC_DC1_ Key, SC EOF Key, SC_ETX Key, 
SC | Escape _Key, SC DEL _ Key, SC_Up Key, 


SC Down Key, SC Left _Key, SC Right _Key, 
SC Not Legal. The character passed is mapped 
into one of these elements. SC Not Legal is 
where all characters are mapped which don't 
fit into one of the other ten categories. 
Prefix characters are recognized by this 
function. If you pass a prefix character, a 
nonechoed read is done to get the next 
character (before the mapping is performed). 
In this case, K CH is returned as that 
character. For the ANSI version of Screenops, 
another read may be done (since three 
character codes are used on ANSI terminals). 
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Function SC Scrn_Has 
( What: SC Scrn Command ): Boolean; 


SC Sern Command is a type consisting of the 
following elements: SC Home, SC Eras 8, 
SC Eras EOL, SC Clear Lne, SC Clear Scn, 
SC Up Cursor, SC Down Cursor, SC Left Cursor, 


SC Right Cursor. This function returns TRUE 
if the CRT has the control character passed. 


Function SC Has Key 
( What: SC Key Command ): Boolean; 


SC Key Command consists of the elements 
previously listed in the description of 
SC Map CRT Command. This function returns 
true if the keyboard generates the character 
passed. 
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Procedure SC Use Info 
( Do What: SC Choice; 


VAR T Info: SC_Info Type ); 


This function is used to pass information back 
and forth between a program and the screen 
control unit. Do What may either be SC Get or 
SC Give and indicates whether the program is 
getting information from the screen control 
unit or giving information to it. T Info 
contains various items to be either passed or 
received. The following information is 
contained within T Info. 





Procedure SC Use Port 
( Do What: SC Choice; 
VAR T Port: SC_TX Port); 


This function works like SC Use Info above. 
Ihe. contents of J] Port. are @€1tner passed. or 
received from the screen control unit. T Port 
contains the following information. 


Row, Col, 
Height, Width, 
Cur X, Cur_Y : integer; 
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ERROR HANDLER UNIT 


Under certain circumstances, the p-System 
displays execution error messages. If a code 
segment is needed and the disk containing it 
isn't in the appropriate drive, you are asked to 
replace the disk and press <space> to continue. 
If a program attempts to divide by zero or 
access outside the bounds of a Pascal array, a 
message indicates this and you are asked to 
press <space>, at which point the p-—System is 
reinitialized. 


When certain errors occur, your programs can 
alter the message that is displayed. This is 
useful for applications developers, especially 
those whose customers speak languages other than 
English. 


Format of Error Messages 


Error messages are displayed on one specified 


80-column line. For example, when a code 
segment is needed from a disk that isn't 
present in the appropriate drive, the 


following prompt is displayed: 






This indicates that the segment SEGNAME wasn't 
found on volume in device U. Place the volume 
VOLNAME in the correct drive and press 
<space>. Execution should continue normally. 
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The following example shows the error message 
that occurs when you press the p-System BREAK 
key. 





After <space> is pressed, the p-System is 
reinitialized. 


System error messages, such as these, always 
appear at a fixed position on the screen. The 
default position is the bottom line. (Any 
line can be specified, however.) A BEL 
character (audible beep) is written to the 
console device when the message is written 
out. 


After pressing <space>, the message line 
disappears; and, when possible, the cursor 
returns to its previous position. If a 
program uses UNITREADs or UNITWRITEs to the 
console, the previous cursor position may be 
lost. Use of GOTOXY (but not SC GOTOXY) may 
also lose the previous cursor position. This 
is because the p-System isn't informed of the 
cursor position after these kinds of low-level 
I/O operations. 
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User Control of Error Messages 


Your program may change the line on which an 
error message is displayed. It may also 
change the actual message displayed when a 
code segment is required from a disk that 
isn't present in the appropriate drive for 
blocked devices. If the code file is on a 
subsidiary volume, set the message for the 
principal volume. 


The ERRORHANDLING unit provides’ these 
facilities. The file ERRORHANDL.CODE contains 
this unit. To use ERRORHANDLING, a Pascal 
program should have a declaration similar to 
the following example. 


USES €$U ERRORHAND.CODE} ERRORHANDLING; 


Also, ERRORHANDLING must be available at 
run-time, either in a library or placed into 
the using program's code file with the Library 
UCLITLY. 
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The following procedures are available within 
this unit: 


Procedure Set Error Line 
(Line: Integer) ; 


Procedure Set User Message 
(Drive: Integer; Mesg:String); 


By calling SET ERROR LINE with the desired 
line number as a parameter LINE, your program 
may change the line on which p-System run-time 
error messages are to be displayed. After the 
call to SET ERROR LINE, any run-time error 
messages are displayed on that line until 
SET ERROR LINE is used again to specify 
another line. 


You may change the standard message for code 
segments needed on disks that aren't present. 
By calling SET USER MESSAGE with the DRIVE 
parameter set to the physical device number 
and the MESG parameter set to the desired 
message string. 


Then, if a code segment is required from a 
missing disk in the unit for which your 
program has designated a special error 
message, that message 1s displayed. The 
p-System then waits for you to press <space>, 
whether or not your message actually indicates 
that a space is needed. The message line is 
subsequently erased; the cursor returns to its 
former position, if possible; and execution 
continues. 


3-21 


User Interface 


CAUTION: Your message is destroyed by a 
release if a MARK was called before a 
SET USER MESSAGE. 


NOTE: The physical device numbers are 4, 5, 
and 9 through the maximum number for physical 
disk as configured in SETUP. 


For other kinds of execution errors, a 
standard p-System message is displayed on the 
message line. A fatal error always causes the 
p-System to fail. For nonfatal errors, the 
p-system waits for you to press <space>. The 
message line is then erased, the cursor 
returns to its former position, and execution 
continues (most likely the p-System 
reinitializes itself). 


To proceed from a nonfatal error, press <esc>. 


WARNING: Escaping from a nonfatal error is a 
dangerous practice since system data may be 
corrupted. 


Error message values you set remain in effect 
during the program run, but are reset at 
program termination or whenever p-system 
reinitialization occurs. 
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Your program may reset the error handling 
values to their default values at any time if 
special output is no longer desired. The 
missing code segment message can be reset by 
passing a null string to SET USER MESSAGE. 


Unknown results may occur on console devices 
whose screen width is narrower than the 
message to be displayed. 
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THE COMMAND I/O UNIT 


Command I/O is a unit in the operating system. 
From Pascal, your program should contain the 
statement: 





Then, the following procedures are available to 
the program: 


Procedure Chain 
( Exec Options: String ); 


A call to CHAIN causes the system to X(ecute 
EXEC OPTIONS after the calling program (the 
chaining program) has terminated. The effect is 
that of: (1) manually pressing 'X' to call 
X(ecute; and (2) entering the characters in 
EXEC OPTIONS. Neither the Command menu nor the 
X(ecute prompt is displayed; the system goes on 
to immediately perform the actions indicated by 
EXEC OPTIONS. 


If a program (or sequence of programs) contains 
more than one call to CHAIN, the EXEC OPTIONS 
are saved in a queue and performed on a 
first-in-first-out basis before returning 
control of the system to you. 


To clear the queue, call CHAIN with an empty 
string (for example, "CHAIN('');"). 
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An execution error or an error in an 
EXEC OPTIONS string clears the queue, returning 
control to you. A call to EXCEPTION, described 
below, may also clear the queue. 


CHAIN is a procedure in the operating system's 
COMMANDIO unit; to use it, a program or unit 
must declare 'USES COMMANDIO'. 


Function Redirect 
( Exec Options: String ) : Boolean; 


This should contain only option specifications 
and not the name of a file to execute (to 
execute a program from another program, see the 
CHAIN intrinsic). 


REDIRECT causes redirection by performing all 
the options specified in EXEC OPTIONS. If all 
goes well, it returns true. If an error occurs, 
it returns false. 


If an error occurs during a call to REDIRECT, 
the state of redirection is indeterminate; this 
is a dangerous condition. If REDIRECT returns 
false, your program should follow it with a call 
to EXCEPTION, in order to turnoff all 
redirection. If you don't do this, the results 
are unpredictable. 


REDIRECT is a procedure in the operating 
system's COMMANDIO unit; to use it, a program or 
unit must contain the declaration ‘USES 
COMMANDIO'. 
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Procedure Exception 
( Stopchaining: Boolean ); 


EXCEPTION turns off all redirection. If 
STOPCHAINING is true, then the queue of 
EXEC OPTIONS created by CHAIN is also cleared 
(see the intrinsic CHAIN). 


Whenever an execution error occurs, an 
EXCEPTION (TRUE) call is made (leaving 
redirection on after an error leaves the system 
in an indeterminate state). 


EXCEPTION is a procedure in the operating 
system's COMMANDIO unit; to use it, a program or 
unit must declare 'USES COMMANDIO'. 
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TURTLEGRAPHICS 


Turtlegraphics is a package of routines for 
creating and manipulating images on a graphic 
display. These routines can be used to control 
the background of the screen, draw figures, 
alter old figures, and display figures using 
viewports and scaling. It also contains 
routines that allow you to save figures in disk 
files and retrieve them. 


The simplest Turtlegraphics routines are 
intentionally very easy to learn and use. Once 
you are familiar with these, more complicated 
features (such as scaling and pixel addressing) 
Should present no problem. 


A pixel is a single picture element or point on 
the display. 


Turtlegraphics allows you to create a number of 
figures, or drawing areas. One such figure is 
the display screen itself, and other figures can 
be saved in memory. Each figure has a turtle of 
its own. The size of a figure may be set by you 
(it doesn't need to be the same size as the 
actual display). 


The actual display is addressed in terms of a 
display scale, which may be set by you. This 
allows your own coordinates to be mapped into 
pixels on the display. All other figures are 
scaled by the global display scale. 
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You may also define a viewport, or window on the 
display. This limits all graphic activity to 
Within that port. 


Turtlegraphics is shipped in two ways. If the 
p-System with Turtlegraphics is adapted to a 
particular hardware configuration, then the 
graphic routines are already tailored to the 
display. The unit Turtlegraphics is already 
installed in *SYSTEM.LIBRARY, and a program may 
use its routines by including the following 
declaration: 





If Turtlegraphics is purchased as a separate, 
configurable product, then you must write a 
number of assembly language routines that 
control the graphic display. These routines are 
called by the Turtlegraphics unit and must be 
written and tested before Turtlegraphics may be 
used. 


Turtlegraphics is accessible from FORTRAN and 
BASIC. This is described later in this section. 
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The Turtle 


The turtle is an imaginary creature in the 
display screen that will draw lines as you 
move it around the display. The turtle can 
move in a straight-line (Move), move to a 
particular point on the display (Moveto), turn 
relative to the current direction (Turn), and 
turn to a particular direction (Turnto). 


Thus, the turtle draws straight-lines in some 
given direction. The color of the lines it 
draws can be specified (Pen Color), and so can 
the nature of the line drawn (Pen Mode). 


Wherever the turtle is located, its position 
and direction can be ascertained by three 
functions: Turtle X, Turtle Y, and 
Turtle Angle. 


NOTE: The turtle may be moved anywhere; it 
isn't limited by the size of the figure or the 
size of the display. But, only movements 
within the figure will be visible. 


To use the turtle in a figure other than the 
actual display, you may call Activate Turtle. 
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The following paragraphs describe the routines 
that control the turtle. 


Procedure Move (Distance: Real); 


Moves the active turtle the specified distance 
along its current direction. The turtle 
leaves a tracing of its path (unless the 
drawing mode is "nop"). The distance is 
specified in the units of the current display 
scale (see below). The movement will be 
visible unless the current turtle is in a 
figure that isn't currently on the display. 


Procedure Moveto (X,Y: Real); 


Moves the active turtle in a straight-line 
from its current position to the specified 
location. The turtle leaves a tracing of its 
path (unless the drawing mode is "nop"). The 
X,Y coordinates are specified in the units of 
the current display scale. 


Procedure Turn (Rotation: Real); 


Turns the active turtle by the amount 
specified (in degrees). A positive angle 
turns the turtle counterclockwise, and a 
negative angle turns it clockwise. 
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Procedure Turnto (Heading: Real); 


Sets the direction (the heading) of the active 
turtle to a specified angle. The angle is 
given in degrees; zero (0) degrees faces the 
right side of the screen, and ninety (90) 
degrees faces the top of the screen. 


Procedure Pen Color (Shade: Integer) ; 


Selects the color with which the active turtle 
traces its movements (unless the pen mode is 
"nop"). This color remains the same until 
Pen Color is called again. 


The color of the pen depends on the way the 
video display is set. If your Turtlegraphics 
is already configured, the available colors 
are described in the documentation for your 
hardware. If you must configure 
Turtlegraphics yourself, then the assembly 
language routines you write will control the 
display color; refer to "Installing 
Turtlegraphics," below. 


A sample set of colors might be: 


Black 
Blue 

= Red 
Magenta 
Green 
Cyan 
Yellow 
White 


“NOOR WNFH © 
Hl 
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Turtlegraphics uses a numeric designation for 
color instead of a symbolic designation like 
the word blue or red to maintain the p-System 
language and hardware compatibility. For 
example, while Pascal would allow the use of 
symbolic color designations, BASIC and FORTRAN 
wouldn't. 


The term wild card refers to the standard 
background color of your display. This 
depends on your display hardware and might be 
called a "hard" background (you may or may not 
be able to change it from a _ program—this 
depends on your hardware configuration). In 
Turtlegraphics, each individual figure may 
have its own "soft" background color, which we 
refer to simply as the "background color" (as 
in the discussion below). 


You may also use black and white graphics, in 
which case the colors might be simply: 


0 Black 
1 = White 
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Procedure Pen Mode (Mode: Integer); 


Sets the active turtle's drawing mode. This 
mode doesn't change until Pen Mode is called 
again. 


These are the possible modes: 

O Nop —- doesn't alter the figure. 

1 Substitute —- writes the current pen color. 
2 Overwrite - writes the current pen color. 


3  Underwrite - writes the current pen color. 
When the pen crosses a pixel that isn't of 
the background color, that figure is not 
overwritten. a 


4 Complement - the pen complements the color 
of each pixel that it crosses. (The 
complement of a color is its opposite; the 
complement of the complement of a color is 
the original color.) 


Values greater than 4 are treated as Nop. 


These descriptions apply to movements of the 
turtle. They have a more complex meaning when 
a figure is copied onto a figure that is 
already displayed. 


3-33 


User Interface 


Function Turtle X : Real; 


Returns a real value that is the x-coordinate 
of the active turtle, in units of the current 
Display Scale. 


Function Turtle Y : Real; 


Returns a real value that is the y-coordinate 
of the active turtle, in units of the current 
Display Scale. 


Function Turtle Angle : Real; 


Returns a real value that is the direction (in 
degrees) of the active turtle. 


Procedure Activate Turtle (Screen: Integer); 


Specifies to which figure subsequent 
Turtlegraphics commands are directed. Each 
invocation of this procedure puts’ the 
previously active turtle to sleep and awakens 
the turtle in the designated figure. When 
Turtlegraphics is initialized, the turtle in 
the actual display is awake. The initial 
position of the turtle is (0,0) or the bottom 
left-hand corner of the screen, ready to move 
right. 
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The Display 


We refer to the initial background of the 
display as the wild card color. The wild card 
color (color O) depends on your hardware (or 
it may be possible for you to set it from a 
program). The default is typically black. 
The background color of a Turtlegraphics 
figure may be changed by you with a call to 
Background. This "soft" background epplies 
when drawing mode 1s used, as indicated above. 


A figure can be filled with a single color 
(not necessarily the background color) by 
calling Fillscreen. 


NOTE: If you use Turtlegraphics (or 
customized routines of your own) to alter the 
settings of your display, it is a good idea to 
reset everything before your’ program 
terminates. Usually it isn't possible for the 
display to return to its original state, and 
the p-System software has no knowledge of what 
that original state was. Also, for the system 
to operate correctly, you must follow any 
video mode change with a call to 
Display Scale. 


Procedure Fillscreen 
(Screen: Integer; Shade: Integer); 


Fills the specified figure ("Screen") with the 
specified color ("shade"). If screen = 0, 
which indicates the actual display screen, 
then only the current viewport is shaded. For 
user-created figures, the entire figure is 
shaded. 
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Procedure Background 
(Screen: Integer; Shade: Integer); 


Specifies the backgound color for a figure. 
The initial background color of all figures is 
the wild card color. 


Labels 


It is possible to draw legends, labels, and so 
forth on the display while using the 
Turtlegraphics unit. This is done by calling 
either WChar or WString. The character or 
string appears at the location of the 
currently active turtle. The text is 
displayed in the type font defined by the file 
*OYO LEMS FONT (See "Installing 
Turtlegraphics," below, to find out how to 
define a font). 


Procedure WChar 
(C: Char; Copymode, Shade: Integer); 


Writes a single character at the position of 
the currently active turtle, using the 
indicated pen mode and color. The character 
is always displayed horizontally, regardless 
of the active turtle’s direction. 
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Procedure WString 
(S: String; Copymode, Shade: Integer); 


Writes a string starting at the position of 
the currently active turtle, using the 
indicated pen mode and color. The string is 
always displayed horizontally, regardless of 
the active turtle's direction. 


Scaling 


When you wish to display data without altering 
the input data itself, it is possible to set 
scaling factors that translate data into 
locations on the display. This is done with 
Display Scale. The display scale applies 
globally to all figures. 


Because of the shape of the actual display, 
data for particular shapes (especially curved 
figures) might become distorted when using a 
"straight" display scale. In this case, the 
function Aspect Ratio can be used to preserve 
the "squareness" of the figure. 
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Procedure Display Scale 
(Min X,Min Y,Max X,Max Y: Real); 


Defines the range of input coordinate 
positions that are to be visible on the 
display. Turtlegraphics maps your coordinates 
into pixel locations according to the scale 
specified in Display Scale. 


This procedure sets the viewport to encompass 
the whole display. The display bounds apply 
to input data. For the actual display, these 
bounds can be any values you require, but for 
user-created figures (0,0) is the lower 
left-hand corner. 


If your Turtlegraphics package is tailored to 
your hardware, then the default display scale 
is already supplied. If you purchased 
Turtlegraphics as a separate, configurable 
product, then you must supply the parameters 
for your own display. These must be returned 
by user-written procedure Query Environment. 
(Refer to "Installing Turtlegraphics," below. ) 
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The following lines are an example of a 
default scale. It is simply the array of 
pixels on the FULL display. 





AS an example, if you wish to graph a 
financial chart from the years 1970 to 1980 
along the x axis, and from 500,000 to 
000,000,000 along the y axis, the following 
call could be used. 





After this, calls to turtle operations could 
be done using meaningful numbers rather than 
quantities of pixels. 
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Function Aspect Ratio : Real; 


Returns a real number that is the width/height 
ratio of the CRT. This can be used to compute 
parameters for Display Scale that provide 
square aspect ratios. 


If an application is designed to show 
information where the aspect ratio of the 
display is critical (for example, circles, 
squares, pie-charts, and so forth), it must 
ensure that the following ratio is the same as 
the aspect ratio of the physical screen upon 
which the image is displayed. 





When the Turtlegraphics unit is initalized, 
Min X and Min Y are set to 0. Max X is 
initialized to the number of pixels in the X 
direction, and Max Y is initialized to the 
number of pixels in the Y direction. In order 
to change to different units that still have 
the same aspect ratio, a call similar to the 
following example can be used. 


Display scale(O, 0, 100*ASPECT RATIO, 100); 


This utilizes Function Aspect Ratio described 
above, and makes the y axis 100 units long. 
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Turtlegraphics always treats the turtle as 
being in a fixed pixel location. Changing the 
scaling of the system with a call to this 
routine in the middle of a program doesn't 
alter the pixel position of any of the turtles 
in the figures. However, the values returned 
from X Pos and Y Pos may change. 


Figures and the Port 


You can create and delete new figures, each 
with its own turtle. When a new figure is 
created, it is assigned an integer, and this 
integer refers to that figure in subsequent 
calls to Turtlegraphics procedures. New 
figures can be saved (Put Figure) or displayed 
on, the ‘sereen::(Get_ Figure). 


The actual display is always referred to as 
figure QO. 


The active portion of the display can be 
restricted by calling viewport, which creates 
a "window" on the screen in which all 
subsequent graphics activity takes place. You 
might create a figure, specify the port, then 
display that figure (or a portion of it) 
within the port. Specifying a viewport 
doesn't restrict turtle activity, it merely 
restricts what is displayed on the screen. 
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User-created figures can be saved in p-System 
disk files. 


Function Create Figure 
(X_ Size,Y Size: Real): Integer 


Creates a new figure that is rectangular, and 
has the dimensions (X Size, Y Size), where 
(0,0) designates the lower left-hand corner. 
The dimensions are in units of the current 
display scale. The figure is identified by 
the integer returned by Create Figure. 


When a figure is created it contains its own 
turtle, which is located at the initialization 
position or 0,0 and has a direction of 0 (it 
faces the right-hand side of the figure). The 
turtle in a user-created figure can be used by 
calling Activate Turtle. 


Procedure Delete Figure 
(Screen: Integer); 


Discards a previously created display figure 
area. 
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Though figures may be created and destroyed, 
indiscriminate use of these constructs my 
rapidly exhaust the memory available in the 
p-System due to heap fragmentation. For 
example, a figure may be created using 
Create Figure (or it may be read in from disk 
using Function Load Figure, described below). 
If possible, after that figure is used (for 
example, with a Get Figure, Put Figure, 
Load figure or Store Figure operation), it 
Should be deleted before other figures are 
created. If many figures are created and 
randomly deleted, the heap fragmentation 
problem may occur. 


Procedure Get Figure 
(Source Screen: Integer; 
Corner X,Corner Y: Real; 
Mode: Integer); 


Transfers a user-created figure (the source) 
to the display screen (the destination) using 
the drawing mode specified. The figure is 
placed on the display such that its lower 
left-hand corner is at (Corner X, Corner Y). 
The X and Y positions are specified in the 
units of the current display scale. If the 
display scale has been modified since the 
figure was created, the results of this 
procedure are unpredictable. 
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The following items define the drawing mode 


numbers. 

O Nop — Doesn't alter the destination. 

1 Substitute - Fach pixel in the source 
replaces the corresponding pixel in the 
destination. 

2 Overwrite - Each pixel in the source that 
isn't of the source's background color 
replaces the corresponding pixel in the 
destination. 

3  Underwrite - Each pixel in the source that 
isn't of the source's background color is 
copied to the corresponding pixel in the 
destination, only if the corresponding 
pixel is of the destination's background 
color. 

4 Complement -— For each pixel in the source 
that isn't of the source's background 
color, the corresponding pixel in the 
destination is complemented. 

Values greater than 4 are treated as Nop. 

If a portion of the source figure falls 


outside the display or the window, it is set 
to the source's background color. 
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Procedure Put Figure 
(Destination Screen: Integer; 
Corner X,Corner Y: Real; Mode: Integer); 


Transfers a portion of the display screen to a 
user-created figure using the drawing mode 
specified (see above). The portion 
transferred to the figure is the area of the 
display that the figure covers when it is 
placed on the display with its lower left-hand 
corner is at (Corner X, Corner Y). It She 
display scale has been modified since the 
figure was created, the results of this 
procedure are unpredictable. 


NOTE: When a figure is moved to the display 
by Get Figure, further modifications to the 
display do not affect the copy of the figure 
that is saved in memory. If you wish to save 
the results of graphics work on the display, 
it is necessary to call Put Figure. 
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Procedure Viewport 
(Min X,Min Y, Max X,Max Y: Integer); 


Defines the boundaries of a "window" that 
confines subsequent graphics activities. The 
viewport procedure applies only to the actual 
display. When a window has been defined, 
graphics activities outside of it are neither 
displayed nor retained in any way. Therefore, 
lines, or portions thereof, that are drawn 
outside the window are essentially lost and 
won't be displayed (this is true even if the 
window is subsequently expanded to encompass a 
previously drawn line). The viewport 
boundaries are specified in the units of the 
current display scale. If the specified size 
of the viewport is larger than the current 
range of the display, the viewport is 
truncated to the display limits. 


Pixels 


It is possible to ascertain (Read Pixel) or 
alter (Set Pixel) the color of an individual 
pixel within a given figure. These routines 
are more specific than the turtle-moving 
routines. They are less straightforward to 
use, but give you greater control. 


User Interface 


Function Read Pixel 
(Screen: Integer; X,Y: Real): Integer; 


Returns the value of the color of the pixel at 
the X,Y location in the specified figure. The 
X,Y location is specified in the units of the 
current display scale. 


Procedure Set Pixel 
(Screen: Integer; X,Y: Real; Shade: Intege 


Sets the pixel at the X,Y location of the 
specified figure to the specified color. The 
X,Y location is specified in the units of the 
current Display Scale. 


Fotofiles 


You may create disk files that contain 
Turtlegraphics figures. New figures may be 
written to a file, and old figures restored 
for viewing or modification. 


When figures are written to a file, they are 
written sequentially, and assigned an "index" 
that is their location in the file. They may 
be retrieved "randomly" by using this index 
value. 
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The p-System name for files of figures always 
contains the suffix '.FOTO'. It isn't 
necessary to use this suffix when calling 
Read Figure File or Write Figure File (if 
absent, it will be supplied automatically). 


Function Read Figure File 
(Title: String): Integer; 


Specifies the title of a file from which all 
subsequent figures will be loaded. If a 
figure file is already open for reading when 
this function is called, it is closed before 
the new file is opened. Only one figure file 
may be open for reading at a single time. 
This function returns an integer value which 
is the ioresult of opening the file. 


Function Write Figure File 
(Title: String): Integer; 


Creates an output file into which user-created 
figures may be stored. If another figure file 
is open for writing when this function is 
called, it is closed, with lock, before the 
new file is created. Only one figure file my 
be open for writing at a single time. This 
function returns an integer result which is 
the ioresult of the file creation. 
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Function Load Figure 
(Index: Integer): Integer; 


loads the indexed figure from the current 
input figure file and assigns it a new, 
unique, figure number. An automatic 
Create Figure is performed. If the operation 
fails for any reason, a Figure Number of zero 
(O) is returned. 


Function Store Figure 
(Figure: Integer): Integer; 


Sequentially, writes the designated figure to 
the output figure file. The function returns 
an integer that is the figure's positional 
index in the current output figure file. 
Positional indexes start at one (1). If the 
index returned equals zero (0), Turtlegraphics 
didn't successfully store the figure. 
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Routine Parameters 


The following shows the interface section for 
the Turtlegraphics unit, including the 
parameters to all Turtlegraphics routines: 


unit Turtlegraphics; - 
‘interface - 


procedure bee Scale( min ne min.y,. <2 >> 
aie max_ My: max yt reat); 
Sruheedon Aspect - Ratio : real; aaa 
function Create at dare’ x Size; ‘ys ‘sizer Bettas od ee ar 
Teal ). integer;- < 
“procedure delete _Figure( screen: EPS SR ER 
re alee’ integer )>;. 
tae procedure. Viewport ¢ min. x; min_y, max x,. °° 
ar ga% max. a : real D3 





- procedure PiU Sercéatoocreens : 
Pk WG ae OSs ; integer; ‘shade: n 
. integer): % 
proeeairs Background’ ‘screen: integer; 
: _ . Shade : integer ); — 
funct ion Read | Pixel screen: integer; _. se aa he's 
Pk; x,y 2 real. ) rinteger; -- 
procedure. Set Pixel screen: integers 
42h pyireal; shade: integer’ ye 
: procedure | Get _Figuret source _ screen: sn 
AR “integer; Ao Ste 3 
corner x, corner yt regalo 
sett ae “copymode : eo eee 
* procedure ‘Put. “Figuret destination screen: 


‘integer; : 


corner x, corner_ i reals. 


- mode “integer 5 


__ funet fon. Read I Figure_ Filec title : he: yr 


te oi integer; 
_ funetion write. _Figure_ File title. - string: Dare 
a eh integer; “3 
~ funetion: toad. Figure index : “integer” Fee 
eS el ot a een aed = integer; 
function Store_Figure( figure: 4 esse ee 
-antegery. 
‘procedure Activate _Turt Lec screen: — 


integer ): 3 


i 


function. Peete x <3 tees 
function: Turtle. Ye CRBAES 85s Reena eases a : 
function Turtle Angle = real; 70 ee 

procedure Move(. distance : real.d3;.°~ ; ek ee Ran 
procedure Moveto(€. x,y: real); 

procedure Turn( rotation t-Feal 23° 
procedure Turntot direction : real );. 

procedure. Pen Mode( state integer ; ye aes ein 
_. procedure Pen_ Colors shade integer foes oe eT AAR berate ater | 
a procedure WChar( c: chars PupyMEGe: shade: integer: ee gear 
-. procedure wstring( Si. stringy copynode, shade: ‘integer; | - 
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Sample Program 


Here is a sample program that illustrates a 
number of Turegraphics routines: 


program Spiraldemo; 
uses Turtlegraphics; 


const nop = 0; 
substitute = 17. 


‘var I, J, Mode: integer; 
C: char; 
Color: integer; 


Seed: integer; 
LX, LY, UX, UY: real; 


fonction Random (Range: integer) : integer; 
begin — 
Seed:= Seed * 233 + 113; 
Random:= Seed mod Range; 
Seed:= Seed mod 256; . 
end; 


faue ClearBottom; 
{clears bottom. line of screen 
for prompts} 
begin 
Penmode (nop); 
Moveto (0, 0); 7 
WString C' ", substitute, 1); 


end; 
begin | fy 
.ClearBottoa; {various initializations} 


WString C'ENTER RANDOM NUMBER: ", substitute, 1); 
-read(keyboard, Seed); 
CiearBottoa; 
Display Scale (0, 0, 200*Aspect anarias 200): 

{Aspect _ Ratio eed so 

pattern will be round} 
Color:=.0;- Hie : 
WString ("ENTER VIEWPORT LL CORNER: ‘, substitute, 1); 
read(keyboard, LX,LY); ; 
ClearBottom; ; 
WString CENTER VIEWPORT UR CORNER: “+. substitute, 1); 
-read({keyboard,. UA UTIs . 
ClearBottom; 
WString (*PENMODE= ', SUBSRLEUES = 
read(keyboard, MODE); 











palette (0); Sete : 
{O= black, 1=green, 2=red, 3=yellou} 
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ViewPort (LX, LY, UX, UY); . {create port} 
PenMode (0); — sie 
fuse blank pen while moving it} - 
Moveto (100*Aspect Ratio, 100); 
{put turtle in center of port} 
{Aspect Ratio ensures that it will be 
correctly centered} 
PenMode (Mode); 
{set pen to selected color} 
J:= Random(90) +90; 
{angle by which turtle will move 
note that turtle begins facing right 
and will move counterclockwise 
(J is positive)} 


for I:= 2 to 200 do 
{draw spirat in 200 segments 
of increasing Length} 
begin 
{cycle through the colors} 
Color:= Colort+1; 
if Color > 3 then Color:= 1; 
PenColor (Color); 
Move(I); 
Turn(J); 
end; 


Iz= Create Figure CUX=LX, UY-LY); 
{create figure the size of the port} 
PutFigure (I, LX, LY, 1); 
{save it; mode overwrites 
old figure (Cif any)} ~ 
ViewPort (0, 0, Aspect _Ratiox200, 200); 
{respecify viewport in 
the lower teft-hand corner} 
GetFigure (1, 0, 0, 1); 
{display finished spiral} 
readln; 
{clear user input buffer} 
end. 
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Using Turtlegraphics from FORTRAN 


Using the Turtlegraphics routines from FORTRAN 
requires accessing special interface units at 
compile time. This is because the Pascal 
syntax contained in the standard 
Turtlegraphics unit isn't compatible with 
FORTRAN. In order to use Turtlegraphics from 
FORTRAN, the FORTRAN source program must 
contain a directive similar to this: 


SUSES TURTLEGRAPHICS IN FIN.TURTLE.CODE 


The Turtlegraphics unit in FTN.TURTLE.CODE 
contains the special interface section that is 
FORTRAN compatible. It is accessed at compile 
time only. During program execution, the 
Turtlegraphics unit in SYSTEM.LIBRARY is 
accessed automatically. 


In addition, there are two fune¢tions, 
Readfigurefile and Writefigurefile, and one 
procedure, Wstring, that can't be directly 
referenced from FORTRAN. Instead, a separate 
unit called FTURTLEGRAPHICS exists to provide 
the support necessary to pass FORTRAN 
arguments to these three routines. In order 
to call Readfigurefile, Writefigurefile or 
Wstring, a directive similar to this: 


SUSES FTURTLEGRAPHICS IN RTLIB4.CODE 


3-53 


User Interface 


must appear in the FORTRAN’ program. 
RTLIB4.CODE refers to the name of the FORTRAN 
run-time library. 


In order to call the Turtlegraphics routines 
from FORTRAN, the following general guidelines 
should be obeyed: 


@ FORTRAN allows identifiers to be a maximum 
of six characters only. PASCAL routines 
with longer names need to be truncated when 
they are called from FORTRAN. 


@ PASCAL boolean variables are referred to as 
logical in FORTRAN. 


@ FORTRAN refers to procedures’ as 
subroutines. The word CALL must precede 
the subroutine name in FORTRAN to indicate 
a subroutine or procedure call. 
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The remainder of this section describes the 
parameters of the routines uSing_ the 
appropriate FORTRAN syntax. 


SUBROUTINE MOVE (€ DISTANCE ) 
REAL DISTANCE 


SUBROUTINE MOVETO ( X, x ) 
REAL X, ¥ 


SUBROUTINE TURN ( ROTATI ) 
REAL ROTATI. 


SUBROUTINE TURNTO © HEADIN )-. 
REAL HEADIN : 


SUBROUTINE PENCOL. C SHADE ) 
. INTEGER SHADE 


SUBROUTINE PENMOD ( MODE.) 
INTEGER MODE 


REAL FUNCTION TURTLX ( )- 
REAL FUNCTION: TURTLY. ( ) 
REAL FUNCTION TURTLA » 


SUBROUTINE: ACTIVA (¢ SCREEN ) 
INTEGER SCREEN 


SUBROUTINE FILLSC € SCREEN, SHADE.) 
INTEGER SCREEN,. SHADE 


SUBROUTINE ‘BACKGR ¢ SCREEN, SHADE ) 
INTEGER SCREEN, SHADE 


SUBROUTINE DISPLA: (© MINX, MINY, MAXX, MAXY ) 
REAL .MINX, -MINY, MAXX, MAXY 


REAL FUNCTION. ASPECT ¢ ) 


INTEGER FUNCTION CREATE (¢ salen: YSIZE ) 
REAL XSIZE, YSIZE 


SUBROUTINE DELETE -¢ SCREEN ) 
INTEGER meREEM 


SUBROUTINE GETFIG ( SOURCE, XCOR, YCOR, MODE ) 
INTEGER SOURCE, MODE ; 
REAL XCOR, YCOR 


SUBROUTINE PUTFIG € DESTIN, XCOR, ACORs MODE ) 


INTEGER DESTIN, MODE 
— REAL XCOR, YCOR 


INTEGER FUNCTION READPI ¢ SCREEN: oe Y) 


INTEGER SCREEN 
REAL X, Y 
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The following three routines are contained in 
the FORTRAN interface unit, FTURTLEGRAPHICS, 
in the FORTRAN run-time library. Because a 
character string can't be passed directly to 
Cue functions Readfigurefile and 
Writefigurefile and the procedure Wstring, the 
FORTRAN routines FREADF, FWRITE and FWSTRING 
must be called instead. 


For the functions FREADF and FWRITE, TITLE 
refers to the name of the Fotofile which is to 
be read or written and LEN contains the length 
of the TITLE variable. 
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The following FORTRAN statements are necessary 
to call them: 





For FWSTRING, C is actually a string of length 
LEN which is to be written in mode COPYMODE 
with shade SHADE. 





To call FWSTRING, the following FORTRAN 
statements are necessary: 
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Using Turtlegraphics From BASIC 


Using the Turtlegraphics routines from BASIC 
requires accessing a Special interface unit at 
compile time. This is because the Pascal 
syntax contained in the standard 
Turtlegraphics unit isn't compatible with 
BASIC. In order to use Turtlegraphics from 
BASIC, the BASIC source program must contain 
directives similar to these: 





The Turtlegraphics unit in BSC.TURTLE.CODE 
contains the special interface section that is 
BASIC compatible. It is accessed at compile 
time only. During program execution, the 
standard Turtlegraphics unit in SYSTEM.LIBRARY 
is accessed automatically. 


In addition, the procedure Wchar contains a 
parameter of type CHAR which was changed to 
type INTEGER for BASIC, when calling this 
procedure the DIM var*l1 variable in BASIC must 
be changed tc an INTEGER. 
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In order to call the Turtlegraphics routines 
from BASIC, the following general guidelines 
Should be obeyed: 


@ BASIC doesn't allow imbedded reserved words 
in identifiers, no identifiers should have 
this characteristic. 


@ BASIC refers to procedures as subroutines. 
The word CALL must precede the subroutine 
name in BASIC to indicate a subroutine or 
procedure call. 
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The remainder of this section describes the 
parameters of the routines using’ the 
appropriate BASIC syntax. 


SUB DSPSCALE (MINX, MINY, MAXX, MAXY >. 
_ REAL MINX, MINY, MAXX, MAXY » | 


DEF REAL ASPECTRATEIO | 


DEF INTEGER CREADFIGURE ¢ XSIZE, YSIZE ) 
REAL XSIZE, YSIZE. ar 


SUB DELETEFIGURE (SCREEN. ) 
INTEGER SCREEN | 


SUB VIEWPORT (¢ MINX, MINY, MAXX, MAXY ) 
REAL MINX, MINY, MAXX, MAXY.. 


SUB FILLSCREEN ( SCREEN, SHADE ) 
- INTEGER SCREEN, SHADE 


SUB BACKGROUND (¢ SCREEN, RARE. cs 
INTEGER SCREEN, SHADE. 


DEF INTEGER RDPIXEL (SCREEN, X,Y) 
INTEGER SCREEN 

REAL X, Y | 

SUB SETPIXEL ( SCREEN, -X, Y, SHADE ) 

INTEGER SCREEN, SHADE | . 

REAL X, Y 

- suB GETFIGURE ( -SOURCESCREEN, CORNERX, CORNERY, COPYMODE ) 
INTEGER SOURCESCREEN, COPYMODE 
REAL CORNERX, CORNERY » - 

UB PUTFIGURE ( DESTINATIONSCREEN, CORNERX, CORNERY, COPYMODE) 
INTEGER DESTINATIONSCREEN, COPYMODE 
REAL CORNER, CORNERY 


DEF INTEGER RDFIGURE ( TITLE ) 
om TITLES*8 


DEF INTEGER WRTFIGURE ( TITLE Socks 
DIM TITLES*8.. : 


DEF INTEGER LDFIGURE ¢ INDEX ie 
, INTEGER INDEX 


DEF INTEGER STORFIGURE 4 ‘SCREEN te 
INTEGER SCREEN 


- suB- ACTIVATETURTLE- ¢ SCREEN 7” 
INTEGER SCREEN 


DEF REAL TURTLX 
‘DEF REAL TURTLY 


DEF REAL TURTLANGLE 
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SUB MOVE € DISTANCE ) 
REAL DISTANCE 


SUB MOVETO ( xX, Y) 
REAL X,Y - 


SUB TURN ( ROTATION ) 
REAL ROTATION 


SUB TURNTO ( DIRECTION ) 
REAL DIRECTION 


SUB PENMODE ( STATE ) 
INTEGER STATE 


SUB PENCOLOR ( SHADE. ) 
INTEGER SHADE 


SUB WCHR. ( C, COPYMODE, SHADE ) 
INTEGER C, COPYMODE, SHADE 


NOTE: To call procedure, WCHR the following 
instructions must be used: 


INTEGER C 
DIM S$*1 


c= ASC(S) (* § contians the character to print®) 
CALL WCHR ( C, COPYMODE, SHADE. ). 


SUB WSTR ¢ S, COPYMODE, SHADE ) 


-DIM S$ 
INTEGER COPYMODE, SHADE 
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Installing Turtlegraphics 


Turtlegraphics has been designed to facilitate 
the development of portable graphics 
applications. Turtlegraphics is distributed 
in two forms. Some systems are distributed 
with Turtlegraphics already configured into 
the *SYSTEM.LIBRARY and ready to run. 
Turtlegraphics is also sold in an adaptable 
form. This document describes how to install 
adaptable Turtlegraphics on your system. 


The adaptable Turtlegraphics package is 
contained in the following seven files: 
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To install Turtlegraphics on your p-System, it 
is necessary to write a collection of 
low-level graphics routines in assembly 
language and link them into one of the GRAFIX 


files. These routines perform simple 
functions such as set a point to a specific 
color, or drawing a line segment. 


Turtlegraphics builds upon these simple 
routines to provide higher level services to 
UCSD Paseal, BASIC, and FORTRAN. If you 
aren't already familiar with Turtlegraphics, 
you should stop and read its description in 
Chapter 1 of this manual for your particular 
hardware. The following section, entitled 
"Graphics I/O Routines," explains these 
low-level routines and the structures. they 
manage. It also provides some implementation 
hints to help you get the best performance 
from your system. 


Some systems require special initialization 
prior to performing graphics I/O. For 
example, it is often necessary to disable a 
hardware character generator on memory-mapped 
displays before you can write to individual 
Screen picture elements (pixels). Similarly, 
at the end of graphics I/O it is sometimes 
necessary to perform special operations to 
restore the system display to normal 
operation. 
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Such initialization and termination is handled 
by the initialization and termination code of 
the USERGRAPHICS unit. If your system 
requires some sort of graphics initialization 
or finalization, you will have to develop a 
custom USERGRAPHICS unit. The "Graphics 
System Initialization" section, presented 
later in this chapter, describes how to tailor 
the supplied unit to suit your requirements. 
If your system requires no-~ special 
configuration to perform graphics I/O, skip 
the "Graphics System Initialization" section, 
use the dummy unit supplied. 


The file *SYSTEM.FONT contains a dot matrix 
character representation that is used by the 
Turtlegraphics routines WChar and WString. A 
subsequent section, "Character Fonts," 
describes the structure of *SYSTEM.FONT and 
how to build a custom version. It is strongly 
recommended that you don't replace the default 
file until the rest of Turtlegraphics is 


working. The EXERCISE program and 
Turtlegraphics error handlers expect a valid 
font to be available. "Linking and 
Librarying," below, describes the ways 


Turtlegraphics may be libraried into a 
p-System. It also describes the use of the 
EXERCISE program in debugging a Turtlegraphics 
adaptation. 
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Graphics I/O Routines 


The Turtlegraphics unit is created by 
linking seven assembly code I/O routines 
into either GRAFIX2.CODE or GRAFIX4.CODE. 
These routines interact not only with the 
system display, but also with a collection 
of data structures that describe the state 
of Turtlegraphics. 


None of the routines described in this 
section need to perform range—-checking on 
the parameters passed, EXCEPT for Draw Line. 
When any of these routines (except 
Draw Line) are to be called, Turtlegraphics 
performs the appropriate range-—checking 
beforehand. 


The following subsections describe the 
syntax and semantics of these routines. 
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Procedure Query Environment 
(Var DisplayDesc: DisplayRec) ; 


Turtlegraphics uses this procedure to 
initialize the parameters that describe the 
target configuration. Query Environment is 
passed a pointer to a record that describes 
the machine-dependent aspects of the system. 
All, the fields must be filled by this 
routine. The Pascal description of the 
record below comes from Turtlegraphics. 
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Function Figure Size 
(Screen: ScreenPtr): Integer; 


This function tells Turtlegraphics the 
number of words required to store the figure 
described by the indicated ScreenRec on the 
target machine. This function is called by 
Create Figure when an application 
dynamically creates a figure. The size of 
the figure varies. Typically it is a 
function of the figure area times the number 
of colors available. 


The encoding of user-created figures is 
completely managed by the low-level routines 
you are writing. You may elect to encode 
your figures for maximum data compression if 
your applications store many figures. You 
may encode for maximum update efficiency, if 
you have a great deal of available storage. 


On systems with large physical memory 
capacity, you my elect to store the first 
several user figures outside of the 
Stack/Heap address’ space. In that 
Situation, the figure size can be zero. 
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The type ScreenPtr is a pointer to a Pascal 
record that describes the state of a 
Turtlegraphics figure. There iS one screen 
description record for every Turtlegraphics 
figure, including the actual display. 


ScreenRec; 


ScreenPtr 


ScreenRec: = 
record 

Valid: ScreenPtr; {pointer should always be a self 
reference when figure is valid} 

FigPtr: fig; {potnter to the figure's locn in memory; 
a nil pointer indicates that the record 
describes the actual display} 

Color: integer; {current pen color} 

Backgnd: integer; {current turtle background color} 

Mode: integer; {current turtle drawing mode} 

{the eee tanh values delimit the viewport by pixel values:} 

MinXPix: integer; 

MinYPix: integer; 

MaxXPix: integer; 

MaxYPix: integer; 


XPix: integer; {turtle pixel x position} 
YPix: integer; {turtle pixel y position} 


TargetStamp :integer; {target machine stamp which identifie 
the machine configuration upon which the figure 
was created; it is updated only by low-level 


yes routines} 
Size: integer; {size of the figure in words} 
XPos: real; {turtle x posn in display scale units} 
YPos: real; {turtle y posn in display scale units} 


Heading: real: {current orientation of the turtle} 
ScaleStamp: integer; (Specifies the scale generation value 
for which XPos and YPos are valid} 
end; , 
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Function Read Screen Pixel 
(Pointer: ScreenPtr; 
XPixel, YPixel: Integer): Integer; 


The Read Screen Pixel function returns the 
color of the pixel at the specified location 
in figure. The XPixel and YPixel parameters 


give the pixel location. Turtlegraphics 
checks the range on all ealls to this 
routine. If the FigPtr in the indicated 


screen record is nil, then the function 
should return the state of the actual 
display. 


Procedure Set Screen Pixel 
(Pointer: ScreenPtr; 
XPixel, YPixel: Integer; 
Shade: Integer); 


The Set Screen Pixel procedure sets the 
pixel at (XPixel, YPixel) to the designated 
color. Shade specifies the color value. If 
the FigPtr in the indicated screen record is 
nil, then the procedure should modify the 
actual display. 
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Procedure Comp Screen Pixel 
(Pointer: ScreenPtr; 
XPixel, YPixel: Integer); 


The Comp Screen Pixel procedure complements 
the pixel at (XPixel, YPixel). Shade 
specifies the color value. If the FigPtr in 
the indicated screen record is nil, then the 
procedure should modify the actual display. 


The definition of complement is left to the 
discretion of the implementor for a given 
target machine, given the following 
constraints—complementing a pixel must 
result in a different unique color, the 
complement of which is the original color. 
This implies that a machine which supports 
Turtlegraphics must have an even number of 
colors in its palette, or that only an even 
number can be used. 


Procedure Fill Color 
(Screen: ScreenPtr; Shade: Integer); 


This procedure fills a portion of the 
specified screen with the designated color 
value. The contents of the screen record 
fields MaxXPix, MinXPix, MaxYPix, and 
MinYPix describe the rectangular area that 
is filled. The FigPtr contains a pointer to 
the area of memory in which the figure is 


stored. If FigPtr is nil, the actual 
display (or a portion of it) should be 
filled. 
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Procedure Draw Line 
(Pointer: ScreenPtr; 
StartX, StartY, EndX, EndY: Integer); 


Draw Line is the most complex routine to be 
written for Turtlegraphics. It must draw a 
line segment in the specified screen. The 
Starting and ending points of the line 
Segment are described by (StartxX, StartyY), 
(Endx, EndY). 


IMPORTANT : Turtlegraphics does no range 
checking on the line segment. The 
implementor is responsible for computing all 
the points in the line segment, and ONLY 
plotting those within the viewport. (The 
viewport is defined by the screen record 
fields MaxXPixel, MaxYPixel, MinXPixel and 
MinYPixel.) In addition, the points on the 
line must be plotted using the PenColor and 
Mode specified in the screen record. The 
valid mode values and their meanings are 
described below: 


const 
nop 0; 
substitute = 1; 
overwrite = 2; 
underwrite = 3; 
complement = 4; 


If the current mode is Nop, Draw Line is NOT 
called. 
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Substitute mode calls for every visible 
point on the line segment to be 
unconditionally plotted. 


Overwrite, for the purposes of Draw Line, is 
the same as Substitute. 


Underwrite mode indicates that visible 
points on the line segment are plotted only 
if the pixel at that location is currently 
set to the Backend color, as described in 
the screen record. 


Complement mode indicates that the visible 
points on the line segment should be 
complemented using the definition of 
complement used by the Comp Screen Pixel 
procedure. 


The performance of Turtlegraphics is 
strongly influenced by the efficiency of 


these routines. It is recommended that 
every effort be made to optimize their 
operation. Computing the line trajectory 


and then only performing simple addition to 
determine the locus of the next point is a 
good way to minimize computing. A 
"psuedo—Pascal" procedure below outlines how 
Draw Line might be structured: | 
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procedure Draw Line 
(Screen: ScreenPtr; 
StartX, StartY, EndX, EndY: integer); 


var Temp, X, Y, Deltax, DeltaY, Cnt, 
XInc, XResidue, XCorrection, 
YInc, YResidue, YCorrection: integer; 


DXNeg, DYNeg: Boolean; 


procedure exchange xy; 

begin 
Teap := Startx; 
StartX s= EndXx; 
EndX := Temp; 
DeltaxX := -DeltaXx; 
Temp := StartyY; 
StartY := EndY; 
EndY := Temp; 
DeltaY <= -DeltaY;> 
DXNeg := not DXNeg; 
DYNeg := not DYNeg; 

end; 


procedure update pix (px, py: integer); 
begin 
with Screen 
do begin 
if (px>=MinXPix) and (px<=MaxXPix) and 
Cpy>=RinYPix) and (py<=MaxYPix) 
then 
case mode of 
substitute, overwrite: 
set_screen_ pixel (Screen,px,py,color); 
underwrite: 
if read screen_pixel (Screen,px,py) =backgnd 
then set_screen_ pixel (Screen,px,py,color) ; 
complement: 
comp screen pixel {Screen,px,py) ; 


end; 
end; 
end; 
begin 
Deltax 


s= EndX - Startx; 
DeltaY == EndY -— StartY; 
DXNeg := Deltax<O0; 
DY¥Neg := DeltaY<0O; 
Tf DeltaX = 0 then {vertical Line} 


begin 
if DYNeg then exchange xy; 
for Y:=StartY to Endy 
do update pix (Startx, Y) 
end 
else if DeltaY = 0 then horizontal Line} 
begin 
if DXNeg then exchange xy; 
for X:=StartX to Endx 
do update pix (X, Starty) 
end 
else if abs(DeltaY) > abs(Deltax) then 
{abs (slope) > 45 degrees} 


3-73 


User Interface 


end; 
end 


beain 


if DYNeg then exchange xy; 

{substitute for fractions:} 

YInc := abs((64 * DeltaY) div DeltaX); 

{using binary fixed point arithmetic operations:} 
YCorrection := Yinc mod 64.+ 1; 

YInc :=-YInc div 64; 

Y = Starty; 

X := Startx; 

YResidue <= Q; 

Cnt :=.0; 


-while.Y <= Endy; 
| do begin 


update pix (X, Y); 
Y :=.Y¥+1; 
Cnt s= Cntt#1; 
if Cnt=YInc then 
if. YResidue > 64 then 
begin 
Cnt z= Cnt “4; 
YResidue <= YResidue = 64 


end 
else 
begin. 
YResidue := YResidue + YCorrection; 
€nt := 0; : 


if DXNeg then X : 


= X-1 
else X := X + G 


end; 


else {abs(slope)<= 45 degrees} 


end; 


begin. 


if DXNeg ‘then. exchange xY? 

{substitute for fractions:} | . 
XInc:=abs((64 * DeltaXx) div peltaY);” 

{using binary. ‘fixed point arithmetic operations: } 


-XCorrection := XInc mod 64 © +. 4= 


XInc := XInc div 643 — 
X s= Startx; 
Y := Starty; 


- MResidue := 0; 


Cnt <= O7 
white x <= EndX 
do begin. 
update pix (x, y);- 
X s= X¥1>.—-- 
. Cnt == Catt; 
tf Cnt=X Inc: then: 
if. XResidue > 64 then 

begin 
Cnt := Cnt te 
. XResidue := XResidue - 64 

end 

else 

begin : 
XResidue := xResidue + XCorrection: 
‘Cnt s= 0; 
if DYNeg | then Y := Y-1: 

else Y r= ¥ +1; 
end; 
end; 


end; 
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Graphics System Initialization 


It is frequently necessary to perform some 
special operations to ready a system to 
display graphic information. On some 
systems, for example, the display hardware 
must be switched into a different mode. 
Similarly, at the termination of graphic 
I/O, it is often necessary to perform some 
operations to restore the system to normal 
operation. 


Turtlegraphics addresses this situation by 
expecting a unit called USERGRAPHICS to be 
in *SYSTEM.LIBRARY. This unit has one 
procedure: 


procedure Hardware config; 4° 


When Turtlegraphics is performing 
initialization it calls Hardware Config. At 
the end of a program, any termination code 
present in the USERGRAPHICS unit is 
executed. 
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Turtlegraphics is shipped with a _ skeleton 
version of USERGRAPHICS in the file 
USRGRAFS . This may be used if no special 
initialization or termination is required. 
If your system requires Special 
configuration, you can write your own 
USERGRAPHICS unit. The only requirement is 
that USERGRAPHICS be in *SYSTEM.LIBRARY, and 
that the FIRST procedure in its interface 
section must be called Hardware Config. 
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Character Fonts 


Turtlegraphics allows programs to label 
figures by calling two special routines, 
WChar and Wstrineg. These routines draw 
characters in figures by using a _ table 
stored in a file called *SYSTEM.FONT. 


The standard system is shipped with a 
character font that contains 128 ASCII 
codes, Similar in style to those on the some 
personal computers. Each character occupies 
an area 8 pixels high by & pixels wide. 
This character size may be inappropriate to 
some displays. On high resolution displays, 
such characters are too small. On low 
resolution displays, it may be desirable to 
use a Ox7 character matrix. 


To replace the default font with one of your 
own design, you must first be sure that your 
version of the function Query Fnvironment 
initializes the display record fields 
CharHeight and CharWidth to the proper 
values. You must then generate a new table 
and save it on the boot disk as 
*SYSTEM. FONT. 
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A Font Structure 


Turtlegraphics reads the font table as a 
1-—dimensional packed Boolean array. To draw 
a character, it computes the index of the 
first bit of a character as follows: 


It then displays the characters, using an 
algorithm similar to: 





Therefore, the font table is designed like 
a: 





Don't use such a declaration to create your 
character font in Pascal. Pascal aligns all 
arrays (packed arrays included) so that all 
rows and columns begin on word boundaries. 
This will cause you problems if the product 
of CharHeight and CharWidth isn't evenly 
divisible by 16. 
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Linking and Librarying 


Once you have written the low-level graphics 
T/O routines, you must link them into one of 
the GRAFIXx.CODE files to produce 2 complete 
Turtlegraphics unit. The standard p-—System 
linker will do the job. Select either 
GRAFIX2.CODE or GRAFIX4.CODE to host your 
linking, depending on the real number size 
of your p-machine. The output file should 
be called TURTLE.CODE. 


NOTE: There are 
least-significant-byte-first and 
most-significant-—-byte-first versions of 
these GRAFIXx files. You should have 
received the Turtlegraphics package which 
corresponds to the byte sex of your 
processor. It isn't possible to link 
assembled routines into a host of the 
Opposite byte sex. 


To run programs that use "Turtlegraphics," 
be sure *SYSTEM.FONT is on the boot disk. 
Also, be sure that *USERLIB.TEXT indicates 
where TURTLEGRAPHICS and USERGRAPHICS may be 
found, or include both units in 
*SYSTEM. LIBRARY. 
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Exercising Turtlegraphics 


Included in the adaptable Turtlegraphics 
package are two exercise programs, 
EXERCISE2.CODE and EXERCISE4.CODE. Both are 
created from the source in EXERCISE.TEXT. 
They are provided to help you debug your 
low-level graphics I/O routines. They are 
programs written in Pascal, and are designed 
to exercise progressively more sophisticated 
aspects of your routines. 


The exercise is divided into two main 
sections. The first section tests graphics 
I/O to the actual display. The second half 
runs a similar set of test on user-created 
figures, and then copies the figures to the 
actual display for your examination. The 
paragraphs that follow explain the operation 
of the exercises. 


Display Set and Clear Pixel Test 


This test should display a set of colored, 
dotted lines horizontally across’- the 
display, drawing a pair from left-to-right 
with each pass. The test should end when it 
has cycled through all the colors available 
on your display. It will then query you to 
see that it has determined the number of 
available colors correctly. For this and 
all subsequent queries, affirm a correct 
result by pressing '‘'Y' (either upper-— or 
lowercase). Any other character is 
considered a negative response, and the 
exercises will terminate. 
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Display Fill Color Tests 


The next set of exercises tests Fill Color. 
First the system calls Fillscreen in all the 
valid colors for your system. You should be 
careful to be sure that Set Screen Pixel 
uses the same color values as Fill Color. 


The next phase of this test should set the 
screen to color O and then display a set of 
overlapping rectangles from the lower 
left-hand corner of the display to the upper 
right, using all the available colors. This 
is a test of windowing in Fill Color. 
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Display Line-Drawing Exercises 


The next portion of the exercises is 
designed to check the Draw Line routine. 
First a set of radial lines are drawn from 
the center of the screen. Thirty-six 
radials are drawn starting at the 3 o'clock 
position, and then move counterclockwise 
around the center point. This behavior is 
repeated for all the nonzero colors. Again, 
be sure that the color assignment matches 
both Fill Color and Set Screen Pixel. A 
sample copy of the sort of display created 
by this test appears in the figure below: 





3-83 


User Interface 


The next part of the tests checks to see if 
Draw Line respects the viewport of the 
display. The system issues the same 
commands as it did on the previous tests, 
but this time the viewport is restricted to 
a small rectangle in the center of the 
display. The result should be that the 
lines should stop at the periphery of the 
rectangle, rather than continuing to their 
previous end points. The figure below shows 
how the display should appear when the test 
is complete: 


Z 
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The last Jine-drawing test on the actual 
display is performed only on systems with 
more than two colors. This checks the 
update modes for line drawing. A small 
rectangular area in the middle of the 
display is shaded. Then the same set of 
radials as before are drawn in each of the 
modes. The expected effects for each mode 
are summarized here: 


QO In Nop mode nothing else should appear. 


1 Substitute mode should draw lines over 
the top of the rectangle and beyond. 


2 Overwrite mode should draw lines over the 
top of the rectangle and beyond. 


3  Underwrite mode shouldn't alter the 
center rectangle. Radials should be 
visible from the periphery of the 
rectangle, continuing out to their 
previous end point. 


4 In Complement mode, the radials should 
emerge from the center point, but change 
color at the periphery of the center 
rectangle and terminate at the edge of 
the screen. 
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User—Created Figures Exercises 


After testing the display, the Exercise 
program performs all the same operations on 
user-created figures. The results of each 
test are indicated on the actual display. A 
frame is constructed on the actual display 


using Fill Color. Your figures resulting 
from each test are copied into this viewing 
frame. 


All the same figures should result, except 


for those that tested viewports, a 
user-created figure can't contain a 
viewport. 


We remind you that a test can prove the 
presence of bugs, but never their absence. 
EXERCISE won't prove that your routines are 
error-free, but if all the tests execute 
successfully, your low-level routines work 
well enough that you can now start using 
Turtlegraphics. 
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QUICKSTART Units 


The code files PEDGEN.CODE and CHKSUMOPS.CODE 
are related to the QUICKSTART utility 
(described in the Operating System Reference 
Manual). These are two standard p-System 
units which may be used by p-System programs 
in order to perform tasks related to the 
quickstarting of programs. 


PEDGEN contains a single routine called 
PED GENERATE. PED GENERATE creates a new code 
file which contains a description of the 
execution environment required by the program. 
This execution environment description is in 
the form of a "Program Environment Descriptor" 
referred to as a "PED." The Pascal interface 
to this unit is described below. 


CHKSUMOPS contains routines to generate and 
validate checksums for p-System code files. 
The Pascal interface to this unit is described 
after PEDGEN. 
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PEDGEN Unit Interface 


Here is the Pascal interface to the PEDGEN 
Unit: 


unit pedgen; 


{This unit contains the standard p-System routine which 
installs a new Program Execution Environment. Descriptor 
(PED). into a program code file.} 


interface 
const max _pedaen. file 1 name length = 2553" 
type pedgen_ file. name = stringlmax: pedgen. filename length]; 


‘pedgen result = {Result codes returnéd by 
PED GENERATE. } 


(pgr no error, 
~ {Result indicating 
successful 
operation. 


pgr lib error, 
{Indicates ‘1/0 error either - 
on open or read of.a 
Sincayy code file. + 


pgr_ lib. output error, 
{Indicates I/O error when 
creating. a copy of -an updated: 
‘Library code file} 


por chksum error, ae TA 
{1/0 error occurred when 
attempting to insert new 
-checksum into. a referenced: 
PE oe code file.} 


> “pac input error, 
{indicates 1/0 error dither 
-on open or read of host — 
program code file.}> 


por | output __ error, : 
{Indicates I/0 error arntinad: 
. PED. to disk file} 


~pgr_ unit _error, 
“{Iindicates failure to locate 
a referenced unit} 


" bad library_ list _error, 
{Library file list text file 
is not a.text file.} 


pgr_lib list_error, 


{Indicates 1/0 error reading 
library file list text file.} 
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pgr duplicate _unit_error, 
zi {A unit name conflicts with 
a System unit name, or the 
system contains more than —_ 
one unit with the same name.} 


pgr Lib. count error, 
{Number of Library files referenced 
by execution environment exceeds 
max Library file refs.} . 


pgr_sys ref count_error, 
{Number of system segments referenced 
by execution environment exceeds 
max system _seg refs.} 


pgr_no program error, 
{Input file i$ not a host 
program, or the operating system 
host unit is missing from an 
. operating system host code file.} 


pgr_no boot seq error, 
{System host code file does not 
contain the required boot segment.} 


pgr_must_be linked error, 

{Program environment references 
a segment which contains 
unresolved references to 
assembly Language routines. 
Thus the program must be 
Linked by the Linker before an 
environment can be constructed.} 


pgr -obsolete_segment_error, - 
{Program contains a reference to 
a segment which was not compiled 
with a Version IV compiler.} 


pgr_not_enough_mem error, 
<Not enough memory to build 
required temporary data 
structures during environment. 
construction process.} 


pgr_buf_ etoutieus error 
{The buffer into which the PED 
is. being generated in not large 
enough to describe the environment 
for the program.} 


25 


{The following is the interface to the PED GENERATE routine itself.} 


function 
ped _ generate 
Cinput_ file id: pedgen _ file ) name; 
{File name of program- code’ file for 
which.a-new PED is to be constructed.} 


output_file_id: pedgen_ file name; 


{File name of new code file to be 
created.} 
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is system: boolean; : 
. {If TRUE the PED fora new ape rarina 
- system is to be constructed which does 
‘not contain. references to. segments of — 
the current epErseteg system. ae 


copy _ input? hos tears 

) _ If TRUE. the PED is inserted in a new ‘copy . 
of the source code file; otherwise the new 
PED is written to the original sun file. } 


_copy_ ‘Libraries: naerean: 

{Controls whether user js. Brome for 
where to copy updated versions of library 
code files into which new checksums have 

- been inserted. > 


write _ progress. messages: boaleans: ee 
{If TRUE progress messages are written 
to. the standard file OUTPUT describing 
how the execution environment is being. or 
constructed.) - 


var the_ jorstt: ‘integer; - 
{When an 1/0 result. is “returned this 3 
-parameter is set to the value of. IORESULT. — 
If no I/O errors occur, this is set to zero.}. - 


var. the | name: spedgen= file name . 

{when a unit or.a Library code file.is 
not found, or an'I/0-error occurs: this 
variable is set to the name of the unit 
or. file. When none of these errors 


occur, this variable is. set to the 
Rik d string. D areas 


2 pene result; 


The INPUT FILE ID parameter specifies the file 
name of the code file for which a Program 
Environment Descriptor (PED) should be 
constructed. The OUTPUT FILE ID parameter 
specifies the file name for the new code file 
to be created. OUTPUT FILE ID is only used 
when the COPY INPUT parameter has the value 
TRUE. 
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The IS SYSTEM parameter is used to determine 
if the program is a new version of the 
p-System operating system. If IS SYSTEM is 
TRUE, PED GENERATE generates a PED that 
doesn't contain any information specific to 
the currently executing operating system. If 
IS SYSTEM is FALSE, the generated PED assumes 
the current operating system environment. 


The COPY INPUT parameter specifies whether the 
PED is to be installed in the existing code 
file, or installed into a copy of the original 
program code file. If COPY INPUT is TRUE, a 
copy of the original program code file is 
written to the file specified by the 
OUTPUT FILE ID parameter; otherwise, the 
source code file is modified to contain a new 
PED. 


This copying process begins by copying the 
segment dictionary blocks of the original code 
file to the designated output file. The 
segments contained in the original code file 
are copied one at a time to the output file. 
When all of the code segments within the 
original code file have been copied, a revised 
segment dictionary is created in a sequence of 
consequtive blocks at the beginning of the new 
code file. The manner in which the contents 
of the original code file are transferred to 
the output code file ensures that a PED 
present in the original code file doesn't 
occupy space in the new program code file. 
Once this copying process is completed, the 
building of a new PED for the program is 
started. This final process consists of 
building the execution environment for the 
program and storing a representation of that 
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environment in the form of a PED in the new 
code file. The PED is stored in the new code 
file by appending it to the end of the code 
file. 


If COPY INPUT is FALSE, the new PED is either 
written on top of an existing PED within the 
original code file, or is appended to the end 
of the original code file. 


During the construction of the program 
execution environment, each referenced library 
code file is checked for the presence of a 
nonzero checksum indicator in block zero of 
the segment dictionary informtion. If this 
checksum indicator is zero, the p—System 
checksum generation unit CHKSUMOPS is called 
to insert a valid checksum into the library 
code file. When the COPY LIBRARIES parameter 
is TRUE, PED GENERATE presents a prompt each 
time a library code file is updated with a new 
checksum. 


This prompt asks if you wish the updated 
library code file to be copied to another 
file. When COPY LIBRARIES is FALSE, no such 
prompts are displayed. A detailed description 
of the characteristics of this facility was 
given in the description of QUICKSTART, above. 


User Interface 


The WRITE PROGRESS MESSAGES parameter is used 
to control whether or not PED GENERATE writes 
progress messages and error messages to the 
file OUTPUT. These messages are generated 
when this parameter has the value TRUE and are 
Suppressed when this parameter has the value 
FALSE. A detailed description of the format 
of the progress messages generated by 
PED GENERATE was given in the description of 
QUICKSTART utility program. 


The following is an example of the type of 
progress messages that would be written to the 
file OUTPUT as the result of a call to 
PED GENERATE with the COPY INPUT and 
WRITE PROGRESS MSGS parameters set to TRUE, 
and the COPY _ LIBRARIES parameter set to FALSE: 
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The reference parameters THE IORESULT and 
THE NAME are used to return information 
pertaining to certain errors. Upon entry to 
PED GENERATE, THE IORESULT is set to the value 
zero, and THE NAME is set to the empty string. 
Whenever PED GENERATE returns the results 
PGR INPUT ERROR, PGR OUTPUT ERROR, or 
PGR LIB ERROR, the value of IORESULT is placed 
in THE IORESULT. When PED GENERATE returns 
the result PGR UNIT ERROR or PGR LIB ERROR the 
name of the unit or library file being 
referenced at the time of the error is placed 
into THE NAME. 


If the segment dictionary of the program 
indicates that the program must be linked 
using the p-System linker, PED GENERATE halts 
and returns the result 
PGR MUST BE LINKED ERROR. 


3-94 


User Interface 


CHKSUMOPS Unit Interface 


Here is the interface to the p-System 
CHKSUMOPS unit: 


7 unit chksumops; 
interface 
const max_chksum.file_name_length = 255; 
type chksum, file nane-= stringlmax_chksum file. name length; 
Schicue test = '¢ 


 ¢chksum_no error, we 
{Checksum operation 
successful} 


chksum_obsolete error, 
{Checksum in code 
'" - file-is obsolete; 
that is, the contents 
of the file have 
‘been changed} 


chksum_io error 
{Error opening, 
reading, or 
-. writing code 
file} 
3 


function. chksum_gen(file id: chksum_file_name; 
var iorslt: integer): 
chksum_result; 


function chksum_check(file_ id: chksum file name; 


var iorslt: integer): 
chksum_result; 
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The CHKSUM_GEN function causes a new checksum 
to be calculated and installed in the checksum 
field of block zero of the code file specified 
by the FILE ID parameter. This function 
returns the result CHKSUM NO ERROR if the 
operation is successful. 


The CHKSUM CHECK function calculates’ the 
correct checksum for the contents of the code 
file specified by the FILE ID parameter. The 
calculated checksum iS compared with the 
checksum stored in the file. If the checksum 
present in the code file isn't zero and 
doesn't match the calculated checksum, this 
function returns the result 
CHKSUM OBSOLETE ERROR; otherwise, the result 
CHKSUM_} | NO | ERROR is returned. 


Both the CHKSUM GEN function and_ the 
CHKSUM CHECK function return the result 
CHKSUM IO ERROR whenever an I/O error is 
detected “while opening, reading, or writing 
the specified code file. If this result is 
returned, the IORSLT parameter is set to the 
value of IORESULT to indicate the nature of 
the I/O error. 


The checksum value zero is reserved to 
indicate the absence of a valid checksum in a 
code file. 


CHAPTER 4 


FILE MANAGEMENT UNITS 


File Management Units 


INTRODUCTION 


Your Pascal programs can use the file management 
units to accomplish several tasks usually 
performed by the filer. There are four file 
management units: 


DIR. INFO.CODE 
WILD.CODE 

SYS. INFO. CODE 
FILE. INFO.CODE 


DIR.INFO provides directory information. Your 
programs may use this unit to: 


List directories. 


Parse file names into volume ID, file name, 
file type, and size specification. 


Change file names. 


Change the date associated with a file or 
volume. 


Remove files. 
Krunch a volume. 
Mount and dismount subsidiary volumes. 


Grant exclusive access rights to a directory 
by task. 


Release those excluSive access rights. 


File Management Units 


WILD provides wild card string matching 
facilities. 


FILE.INFO allows your programs to: 


Determine if files are opened. 
Find the length of a file. 


Determine what storage volume contains a 
given file. 


Extract the file title with its suffix, from 
a file. 


Find the starting block of a file. 


Determine whether or not a volume is a 
storage volume or a communications volume. 


Return the date associated with a file. 


SYS.INFO allows your programs to: 


Determine the device number or volume name of 
the system disk (the volume referred to by 
asterisk, "*"). 


Determine the file names for the work files 
and the volumes on which they reside. 
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INTERFACE SECTIONS 


In order to take advantage of the file 
management units, your Pascal programs should 
use them in a USES declaration. (These units 
aren't available to FORTRAN and BASIC programs. ) 
For example, to have access to all four units, 
you would use this declaration: 





You can then call the routines these units 
contain from your programs. Here are the 
interface sections of the four file management 
units with embedded comments. The routines are 
described in detail throughout the rest of this 
chapter. 


File Management Units 


Unit Interface 
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Unit Interface 


Unit Dir Info; 


Interface 
uses. 
(x$uU- WILD. CODE*) wild; 


Type. 
D_DateRec = Packed Record 
* Month. : 0..123 
Day Ea Ue bas 
Year : 0..100; 
End; 


D_NameType = (D Volt, D Code, D Text, D_Data, D SVol, D_Temp,. D. Free); 
D Choice = Set of D NameType; 


SOs LIStPi ete hee teu 7 “FD aeists 
D List = Record : 2 : 
D Unit: Integer; 
D. Volume: StringL[7J; 
D ) VPat: D -PatRecP; 
D )-Nextentry: D ) ListP; 
Case D IsBlkd: “Boolean Of 
True: (D_Start, { Starting block of entry } 
; D Length: Integer; |< Length Cin blocks). of. entry } 
Case D Kind: D ) NameType Of 
D Vals Us ote, St Everything but D Free ni 
D Temp; 
D Code,’ 
D Text, 
DD _Data, 
ane Vol: CD Title: Stringl15]; C File name * 
DL FPat: D PatRecP; { name pattern info } 
D_ Date: D. ) DateRec; { File date + 
Case D | NameType of { # of files on vol } 
D_Vol: (>. NumFiles: Integer))); 


Unit .# of entry > 

volume name. of unit. } 

volume pattern info } 
Next entry in list } 


ote Toon Th a oa 


End; 


D Result = (D Okay, -_ {Mission accomplished ce 
ea D Not: Found, { Couldn't find: name and/or type + 
.D_Exists, a ‘{ Name already exists; no name change made: + 
D.Name Error,  £ Iklegal- string passed } ae 
D Off Line; { Volume not:on Line}... 
D Other); { Miscellaneous error iP, 


Function D Dir_| List (D .Name: String; D. Select: D. | Choice; 
Var Do Ptr: “D ) ListP; D ) PInfo: Boolean): -D ) Result; 
-€ Creates | pointer to list of names of specified ‘NameTypes 
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-(D Select), matching specified D Name (wild card-characters allowed). 
Includes information about pattern matching that QchUEt es if, requested 
(by D_PInfo) } 


Function D Scan _Title(b Name: String; Var D | Volume, D Title: String; 
oa Var D ) Type: “D _ NameType; Var D Segs: Integer): D Result; 
 { Parses Dd. Name } - 


Function D Change Name —~ 
CD . OldName, - D | NewName: String; D | RemOLd: Boolean) : D Result; 
{ Changes file name in D “OL dName to name in D | NewName, removing already 
existing files of name in D_NewName ag D ) RemOld is set } 


- Function b Change Date(D , Name: String; D _Newdate: D _DateRec; 
Dd Select: D Choice): | D Result; 
 & Changes date of directory or file name in D._Name to. date specified by 
D NewDate. D Name may contain wild cards } 


Function D Rem Files (D Name: string: D Select: D choice): Do “Result; 
{ Removes Tr len of specified name (wild cards al towed) } 


Procedure D ) Lock; 

Procedure D ) Release; 

{ Provide. means to. Lim7t use of Dirinfo routines to one task at a time 
in multitasking ‘environments a: 


Function BD -Krunch CD | Unit, D | Block: Taewuens D Result; 
{ Collects | all unused space on a-volume around D ) Block. This unit must 
not. be in use when this operation is performed. } 


Function D Mount (D_ Fite Name : String) = D Result; 

Function: D_ DisMount (D ) Vol Name : String) : D_Result; 

{ Provides a means: of mount ing and dismounting: subsidiary volumes. 
Wild cards may be used. } 
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Unit Sys Info; 
Interface 


Type SI_Date Rec = Packed Record 
Month : 0..12; 
Day : 0..31;3 
Year : 0..99; 
End; { SI Date Rec } 


Procedure SI Code Vid (Var SI Vol : String); 
{ Returns name of volume containing current work file code } 


Procedure SI Code Tid (Var SI Title : String); 
{ Returns title of current work file code } 


Procedure SI_Text_Vid (Var SI_Vol : String); 
{ Returns name of volume containing current work file text } 


Procedure SI_Text_Tid (Var SI Title : String); 
{ Returns title of current work file text } 


Function SI Sys Unit : Integer; 
{ Returns number of bootload unit } 


Procedure SI Get Sys Vol (Var SI Vol : String); 


{ Returns system volume name ¥_ 


Procedure SI Get Pref Vol (Var SI Vol =: String); 
{ Returns prefix volume name } 


Procedure SI Set_Pref Vol (SI Vol : String); 
{ Sets prefix volume name } 


Procedure SI Get Date (Var SI Date : SI_ Date Rec); 
€ Returns current system date } 


Procedure SI_Set_ Date (Var SI_Date : SI_Date Rec); 
{ Sets current system date } 


Units 
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Unit Interface 


Unit FileInfo; 
Interface 


Type F_File Type = file; 
F Date Rec = Packed Record 


Month : 0..12; 
Day 050215 
Year : 0,.100; 


End; { F Date Rec }: 
Function F_Open (var fid: Furile type) sboolean; 
x Patuaietente if the file is open and false if not open. *) 
Forict ion F Length (Var Fid : “FFile Type) : rotedets 


{Returns the Length of the file attached to the Fid identifier. 
If the file is not opened result is returned as zero} 


Function F_Unit_number (Var Fid : F_File Type) : integer; 


{Returns the unit containing the file attached to the Fid 
identifier. If there is no file opened to Fid, the. function 
result is Zero.}~ 


Procedure F Volume (Var Fid : F File Type; 
Var File Volume : String); 
-{Returns. the. name of the volume containing the file attached 


to the Fid identifier. If there is no file opened to Fid, 
_the file_volume is set to a null string.} 


_ “Procedure FFile Title (Var Fid : F File Type; 
apt, Var File Title s String); 


{Returns the title (with suffix) of the file attached to the 
Fid identifier. If there is no file opened to Fid, 
‘the File title is set to the null string. 
Function F Start (Var Fid :.F_ File Type).: integer; 
{Returns the block numberof the first block-of the file | 
attached -to: the Fid identifier. If there is no file opened 
to Fid, the function result is. returned: is zero.} 


Function. -_is Blocked (Var Fid : F File: Type) : Boolean; 


{Returns a boolean. that is TRUE if the file attached to the. 
Fid identifier is tocated on a storage device. If. there 


is no. file opened. for the Fid or if the unit is not a storage 
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DIRECTORY INFORMATION 


This section describes the directory information 
unit, called DIR INFO, which enables your 
programs to access file system information. 


Many of your applications may need to access and 
modify directory information. This unit makes 
it easy to perform most of these sorts of 
operations. There are other ways to do this. 
The most common solution is to construct your 
own routines that directly access the operating 
system's data structures. However, the 
interfaces provided by this unit make directory 
information access much safer and easier. 


The DIR_INFO unit provides the following 
capabilities to your programs: 


@ Directory Information Access. For any 
on-line storage volume, DIR INFO returns the 
volume name, volume date, number of disk 
files on volume, amount of unused space, and 
attributes of individual disk files. 


@ Directory Manipulation. DIR INFO provides 
routines for changing the date or name of a 
disk file or volume, removing files from a 
volume, and mounting and dismounting 
subsidiary volumes. 


@ File Manipulation. DIR INFO allows you to 


Krunch a volume in a similar fashion to the 
Tiler, 
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@ Wild Cards. DIR_INFO uses the UNIT WILD, 
Which provides a wild card convention for 
pattern matching of string variables. Most 
DIR INFO routines recognize the wild card 
convention in their file name arguments. 


@ Error Handling. DIR_INFO defines a standard 
error result (similar to UCSD p-System 1/0 
results) for routines involved with file 
names and directory searches. 


@ Multitasking Support. DIR INFO provides 
routines for protecting file system 
information from contention between 
concurrent tasks. These routines ensure that 
only one task can modify file system 
information at a time. 


Notation and Terminology 


In this chapter, a variant of Extended 
Backus-Naur Form (EBNF) is used as a notation 
for describing the form of wild cards and file 
names. Meta-words are words that represent a 
class of words; they are shown in the text by 
the use of angle brackets < \ >. The 
following expression is an example: 
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The equal sign ( = ) indicates that the 
meta-—word on the left side can be substituted 
with the word on the right side. The bar ( 
) separates possible choices for substitution. 
In this example, "fish" can be replaced by 
"trout," "salmon," or "tuna." 





An item enclosed in square brackets [ \ ] may 
be substituted into a textual expression. For 
example, [micro]computer can represent the 
text strings computer and microcomputer. 


An item enclosed in braces { \ } can be 
substituted zero or more times into a textual 
expression. The following expression 
represents responses to jokes possessing 
varying degrees of humor. 





Literal occurrences of characters or strings 
of characters are delimited by quotes to avoid 
confusing them with notational definitions. 
For example: 






The term <file-object> 1s used throughout this 
chapter; it is a generic term encompassing 
communications and storage volumes, files, and 
unused areas on storage volumes. 
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File Name Arguments 


Most DIR INFO routines accept file name 
arguments. The file name specifies the volume 
and/or file to be accessed by the routine. 
You should see the Operating System Reference 
Manual for a complete description of p-System 
files and file names if you aren't familiar 
with them. 


Volume names and file names may contain wild 
ecards (which are described in the next 
section). Device numbers and colons 
separating volume [IDs and file names must 
appear literally; they must be independent of 
any wild card. 


All DIR INFO routines except D Scan Title 
ignore file length specification. In some 
cases, file name conventions in DIR_INFO 
differ slightly from p-~-System file name 
conventions: 


@ DIR_ INFO considers an empty 
volume ID/file name argument to specify the 
prefix volume; that is, <file name> is 
empty (implying a volume reference), and 
<volume ID> is empty (implying the prefixed 
volume). An empty string isn't a valid 
file name in the p-System. 
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@ DIR_INFO interprets wild card file names of 
the form <vol-name>:= to be valid volume 
specifiers. This is consistent with 
DIR: INFO"S : derapition .of the .¢ =) wild 
card, but inconsistent with the p-System 
filer's interpretation of the ( =) wild 
ecard. The filer doesn't accept file names 
of this form as volume specifiers. 


File Type Selection 


Some DIR INFO routines accept a <file-type> 
parameter (named D SELECT) which is used to 
specify the file objects to be accessed. 
(File objects include volumes, unused areas on 
storage volumes, temporary files, text files, 
code files, and other types of files.) The 
file type parameter is necessary because file 
names alone can't completely specify all types 
of file objects (such as unused disk areas). 
The routines that generate directory 
information use both the file name argument 
and the D SELECT parameter to determine the 
file objects on which to return information. 
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DIR INFO defines a scalar type, which is used 
to specify file objects. D SELECT is declared 
as a set of this type; a file object is 
selected by including its corresponding scalar 
in D SELECT. 


File object types: 


D NameType = «De Vol. .D Code, Text, 
Db Data, -D-SVol;: BD: Temp, 
Ly Tee), 

D Choice = Set Of D NameType; 


Here is a description of these scalar values: 


@ PD Vol. Selects all volumes matching the 
file name argument. Note that while volume 
names may contain wild cards, device 
numbers must be specified literally. 


@ D Free. Selects all unused areas of disk 
space on the volumes matching the file name 
argument. 


@ D Tem. Selects all temporary files 
matching the file name argument. Files are 
considered temporary if they have been 
opened—and not yet closed—by a program. 


@ PD Text. Selects all text files matching 
the file name argument. 


@ D Code. Selects all code files matching 
the file name argument. 


4~17 


File Management Units 


@ PD Data. Selects all data files matching 
the file name argument. 


@ D Ssvol. Selects all svol files matching 
the file name argument. 


File Dates 


Disk files and disk volumes are assigned 
<file—dates>. File dates are stored in 
records of type D Date Rec. They are accessed 
and modified by the DIR INFO routines 
D Dir List and D Change Date. 


D Date Rec is declared as follows: 


D Date Rec = Packed Record 
Month : 0..12; 
Day : O..31; 
Year >: O..100; 
End; { D Date Rec } 


A year value of 100 in a file date record 
indicates that the object is a temporary disk 
file. (This is a p-System file system 
convention. ) 
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Error Results 


All DIR_INFO routines that access file system 
information return a value reflecting the 
result of the file system operation. This 
result indicates either that the routine 
finished without errors or that an error 
occurred. Valid information isn't returned 
when routines return a result value indicating 
that an error has occurred. 


The following items describe conditions that 
can cause errors: 


@ The specified files, volumes, or unused 
Spaces can't be found in the disk 
directory. 


@ The specified unit is off-line. 
@ The file name argument has improper syntax. 


@ The specified file name conflicts with an 
existing file. 


An error can never cause a function to 
terminate abnormally. Errors that the routine 
can't identify explicity are flagged. This is 
done by returning a result that indicates an 
unknown error has occurred. 


4-19 


File Management Units 


DIR_INFO defines the following scalar type to 
describe the possible errors encountered: 


type DResult.. =. DOkay., 
D Not_Found, 
D EAIStS; 
D Name Error, 
D Off Line, 
D-Other); 


You should refer to the descriptions of the 
various routines for details concerning the 
results of errors and the status of directory 
information returned during error conditions. 


The DIR INFO Routines 


Function D Krunch 
(D Unit:integer; 
D Block: integer):D Result; 


This function Krunches the files on the volume 
specified by D Unit. This is similar to the 
filer's K(runch activity. The block indicated 
by D Block is the point around which the 
unused disk space is consolidated. Files 
located hefore D Block are moved forward 
(toward the directory) and files after it are 
moved backward (toward the last track). 
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NOTE: Using D Krunch on a volume that 
contains an executing or open file (including 
the operating system) may destroy the files. 
If function D Krunch changes the location of 
an open or executing file, the system returns 
data to the previous—not the 
present—location of the file. 


Function D Mount 
(D File Name:String):D Result; 


The D File Name parameter identifies an svol 
file. The corresponding subsidiary volume is 
mounted unless D Result indicates otherwise. 
Wild cards may be used. 


Function D DisMount 
(D Vol Name:String):D Result; 


The subsidiary volume identified by the 
D Vol Name parameter is dismounted. This 
volume must be a subsidiary volume. 


Function D Scan Title 
(D NAME:String; Var D VOLUME, 
D TITLE: String; Var D TYPE: 
D ) NameType ; Var D SEGS: 
Integer): D ) Result; 


D Sean Title parses the p-System file pane 
passed in D NAME and returns the file name's 
volume ID, file name, file type, and file 


length specifies, The function result 
indicates the validity of the file name 
argument. D Scan Title doesn't determine 


whether or not D Name actually exists. 
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D Scan Title accepts the following parameters. 


D NAME. A string containing a p-System 
file name. 


D VOLUME. A string that returns the volume 
ID contained in D NAME. If D NAME contains 
no volume ID or if the volume ID is (:: ), 
D VOLUME is assigned the system's default 
volume name. If the volume ID is ( * ) or 
( *: ), D VOLUME is assigned the system's 
boot volume name. Volume names assigned to 
D VOLUME contain only uppercase characters 
and don't contain blank characters. 


D TITLE. A string that returns the file 
name contained in D NAME. If D NAME 
doesn't contain a file name, D TITLE is 
assigned the empty string. File titles 
assigned to D TITLE contain only uppercase 
characters and don't contain blank 
characters. 


D TYPE. A scalar which returns a value 


indicating the file type of the file name 
contained in D NAME. 
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The following items define D TYPE's scalar 
type: 


D NameType = (D Vol, D Code, D Text, 
D SVol, D Data, D Temp, D Free,); 


D TYPE is set to D Vol if the file name in 
D NAME is empty. D TYPE is set to D Code 
if the file name is terminated by ".CODE", 
or to D Text if the file name is terminated 
by ".TEXT" or ".BACK". D TYPE is set to 
D SVOL if the file name ends with .SVOL (a 
subsidiary volume). If none of the above 
holds true, D TYPE is set to D Data. Only 
the suffix of a file is used to determine 
what type it is. For example, the file 
name SYSTEM.COMPILER is returned as a data 
file because its suffix isn't .CODE. 


D SEGS. An integer that is assigned a value 
indicating the presence of a file length 
specifier in D NAME. The value returned in 
D SEGS is assigned as follows: 


LENGTH SPECIFIER D_ SEGS VALUE 
[ <number > ] <number> 
[*] ~1 
<not present> O 
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D Scan Title returns a function result of 
type D Result. The only scalar values 
returned by D ) Scan Title are D Okay and 
D Name Error; they have the following 


meanings: 


@® D Okay. No Error. 


All information 


returned by D Scan Title is valid. 


@ D Name Error. Illegal file name syntax 
in D NAME. The information returned by 


D Scan Title is invalid. 


Example Program 


Program Scan Test; 
. Uses | 
(*$UWILD.CODE*) 
wild, 
(#$UDIR« INFO.CODE*). 
DirInfo; ae 
-. Var ae 
. Name, 
Volume, ol | 
Title : String; . 
Typ : D  NameType; _ 
Seg Flag : Integer; 
Result =: D. Result; 
Ch: Char; 
Begin wary Scan Test } - 
Writeln('— Dd. ScanTitle Test! 3 














Repeat | 
Writeln; re 
Write(*File name to parse: ve 
Readln (Name) ; ; 
Result :=. D- -ScanTitle(Nane,, volume, Title, | 


Typ, Seq_ Flaq); 
WriteLln(! parsed: les 
case result of 
d_okay:begin 





Writeln(' Volume name —.', Vabimed's 





Writeln(' File name —.', Title) 7 
Write(’ File type — 2G 
Case - Typ Of 


D Text : Writeln(' text beg 
D_ Code : Writetn('code file"); .. 
D~ Data : Writeln('data file’); 














‘D_SVol : Writeln('svol file}; 


End; { Cases } 
Mas Seg Flag <> 0 Then 


Writeln(' Segment flag —-', Seg Flag); 


end: 


end; 
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Function D Dir List 
(D NAME:String; D SELECT : D Choice; 
Var D PTR : D ListP; 


D PINFO : Boolean) : D Result; 


D Dir List creates a list of records 
containing directory information on volumes 
and disk files. This information includes 
volume names and device numbers of storage 
and communications on-line volumes, number 
of files on storage volumes, lengths and 
starting blocks of disk files and unused 
disk spaces, file names and types, and file 
dates. The function result value indicates 
invalid file name arguments, off-line 
volumes, or not-found files. 


D Dir List optionally provides information 
describing how the wild card file name 
argument matched files and/or volumes. 


D Dir List accepts a set specifying the 
file types on which to return information 
and a string containing a file name. 
D Dir List returns a pointer to a linked 
list of directory information records. 
Fach record contains the name of a file or 
volume which matches the file name argument 
and also is one of the types specified in 
the file type set. 
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D NAME. The D NAME parameter contains a 
file name which may contain wild cards. 


D SELECT, The D SELECT parameter is a 
set specifying the directory objects for 
which information is to be returned by 
D Dir List. See the file type selection 
for more information on directory object 
selection. 


D PTR. The D PIR parameter is assigned 
a pointer to a linked list of records 
containing directory information for all 
specified file objects. To be listed in 
a directory, a file object must meet the 
following criteria. 


@ It must reside on ae volume which 


matches the volume ID in D NAME. 


@ if the object is a disk file, it must 


match the file ID in PD NAME. 


@ it must belong to one of the types 


included in D SELECT. 
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The linked list contains one record for 
each file object matched. The records are 
defined as follows: 





The D List record fields return the 
following information for each file object 
in the D Ptr list. 


(> D Unit returns the device number of the 
device containing the object. 


@ PD Volume returns the name of the volume 
containing the object. 


@ D VPat is a pointer to pattern matching 
information collected while comparing 
volumes to the volume ID in D NAME (see 
the section on the wild unit for details 
on pattern matching information). 
D VPat is set to NIL if pattern matching 
information isn't requested. 
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@ D NextEntry is a pointer to the next 
directory information record in the 
TST. It is set to NIL if the current 
record is the last record in the list. 


@ D IsBlkd is set to TRUE if the file 
object is (or resides on) a_ storage 
volume. Records describing serial 
volumes have D IsBlked set to FALSE; the 
remaining fields are undefined. 


The following fields exist only in records 
describing file objects stored on storage 
volumes (that is, D IsBlkd is TRUE): 


@ D Start contains the starting block 
number of the file object. If the 
object is of type D Vol, this value is 
interpreted as the block number of the 
first block on the volume (that is O for 
disk volume). 


@ D length contains the length (in blocks) 
of the file object. If the object is of 
type D Vol, this value is interpreted as 
the total number of blocks on the volume 
(such as 320 for a typical single 
density, 5-1/4" diskette). 


@ D Kind indicates the type of the file 
object described by the current record. 
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The following fields exist only in records 
describing disk file objects other than 
unused disk areas (such as D Kind in 
[D Vol, D Temp, D Code, D Text, D Data, 
D SVol]): 7 


@ D Title contains the file name of the 
object. For objects of type D Vol, this 
field contains the empty string. 


@ D FPat is a pointer to pattern matching 
information collected while comparing 
file names to the file ID in D NAME (see 
wild card UNIT for details on pattern 
matching information). DiFPal: 2S. ‘Set 
NIL if pattern matching information 
isn't requested or if the file ID in 
D NAME is empty. 


@ 1D Date contains the file date for the 
current object. 


@ DNunFiles is valid only for objects of 
type D Vol; it contains the number of 
files in the volume's directory. 


NOTE: An .SVOL file (which contains a 
Subsidiary volume) appears as any other 
file on the principal volume. This means 
that D NumFiles doesn't correspond to an 
.oVOL file. However, when accessed by its 
volume ID, the actual subsidiary volume 
returns with a valid D NumFiles entry. 
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File information is returned (in a linked 
list accessed by D Ptr) in the following 
order: 


1. 


Volume on highest numbered device that 
matches D NAME (if D_Vol is in D_SELECT). 


Files in directory of this volume that 
match D NAME and are of one of the types 
in D SELECT (if a file type is in 
D SELECT). 


Last file on volume 


First file on volume 


Unused spaces on this volume (if D Free 
is in D SELECT). 


Last free space on volume 


First free space on volume 


Volume on lowest numbered device that 
matches D NAME (if D Vol is in D SELECT). 


Files in directory of this volume that 
match D NAME and are of one of the types 
in D SELECT (if a file type is in 
D SELECT). 


Last file on volure 


First file on volume 
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6. Unused spaces on this volume (if D Free 
is in D SELECT). 


Last free space on volume 


First free space on volume 


D_PINFO 


When set to TRUE, the D PINFO parameter 
indicates that pattern matching information 
should be returned in a linked list accessed 
by D PTR. The D WILD MATCH function 
collects this information while comparing 
volume and file IDs; it is useful for 
determining how the wild cards were expanded 
in D_NAME. Information is returned in two 
pointers; one for volume names matched 
(named D VPat) and one for file IDs matched 
(named D FPat). 


The following is an example of pattern 
record lists: 





Two volumes contain files which match 
D NAME: 


BOOT contains TESTS.CODE 


WORK contains TESTS. TEXT 
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For BOOT:TEST5.CODE, D Volume is’ 'BOOT', 


D Title is 'TESTS.CODE', and D VPat returns 
a pointer to the following information. 


1. WildPos is 1, WildLen is 1 
CompPos is 1, CompLen is 4 
('=' matches 'BOOT') 


D FPat returns a pointer to the following 
information. 


1. WildPos is 1, WildLen is 4 
CompPos is 1, CompLen is 4 
('TEST’ matches 'TEST') 


2. WildPos is 5, WildLen is 5 
CompPos is 5, CompLen is 1 
('{1-9}' matches '5') 


3. WildPos is 10, WildLen is 1 
CompPos is 6, CompLen is 5 
('=' matches '.CODE') 


A Similar list is returned for 
WORK: TEST5. TEXT. 


NOTE: If the volume ID in D NAME consists 
of a device number (such as "#5"), the 
volume assigned to the device is defined to 
match the volume ID in D NAME. The Pos and 
Len pointers are set as in the following 


example. 
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A disk volume named "MYDISK" resides in 
device 5. 


1. WildPos is 1, WildLen is 2 
CompPos is 1, CompLen is 6 
('#5' matches 'MYDISK') 


NOTE: D FPat: and D'VPat never contain 
invalid information. If information is 
unavailable or hasn't been requested, the 


pointers are set to NIL. 


Function Result 


D Dir List returns a value of type D Result. 
D Dir List can return all scalar values 
defined in D Result except D Exists; the 
values have the following meanings: 


@ D Okay. Noerror. All D Ptr information 
is valid. 


@ D Not Found. No such file/volume found. 
No match found for D NAME. D Dir List 
sets: .D_Ptr to Nib 


@ D Name Error. Illegal syntax in D NAME. 
D Dir List sets D Ptr to NIL. 
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@ D Offline. Volume off-line. The volume 
specified by D NAME wasn't on-line. This 
error occurs only when the volume ID in 
D NAME doesn't contain wild cards (that 
is, a Single volume is specified, and it 
is off-line). If the volume name in 
D NAME contains wild cards but doesn't 
match any on-line volumes, D Dir List 


returns D Not Found. D Ptr is set to 
NIL. 
@ PD Other. Unknown error. D Dir 


encountered an error it couldn't 
identify, but which interrupted normal 
execution of the function. D Ptr is set 
to NIL. 7 
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Example Program 


The following program is a general purpose 
directory lister; it accepts a string 
containing wild cards and creates a list of 
matching files and (if requested) pattern 
matching information for the files. Note 
that the program uses the MARK and RELEASE 
intrinsics to remove the D Dir List 
information from the heap after the 
information has been used. 


Program Listtest; 

Uses: . 
(x$UWILD.CODE*) 
wild, 
_GSUDIR. INFO.CODE*): — 
- Dirnfo; 


Var 
Select : D choice; a0 
Want_ Patterns : BooLean;. yi “cas acu 
Heap | Ptr : : Integer; 
 Segs : Integer; xs 
Typ : D_NameType; wil 
Volume, Title, Match : String; 
" Result : D Result; a, Spe 
Ch : Char; 
Ptr -: D ListP;. 





- . Procedure GiveChoice choice : String; 
. Kind 2 DL Choice); 


Var. ‘ga 
Ch : Char; 
Begin Rtg aus 
- Write ' ",Choice,* ? '); 





_.Read(Ch); writeln; " age ke 
If Ch-In Cty', '¥'J Then Select = Select + Kind; 
End; GiveChoice } 








Procedure Prune Patterns(PatPtr : D PatRecP;. 

Comp, Wild : String); af eee 

~. Varo. Peewee 
Count : Integer; 


Begin € Print Patterns } 
Count := 1;__ 
Writeln('’type <or> far patterns’ ; 
Readln; Writeln; | 
Repeat 
Writeln('Pattern ', Count , sortie 
With PatPtr Do 
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Begin 
Writeln(€" Comp : °, Comp); 
If CompLen <> 0 Then 





Write (’ *s(CompPos + 9)); 
Xf CompLen. > 1. Then Write(" “+: (CCompLen <-- 1): 
Writeln; 
Writein(® Wild: ", Wild); | 
Write’ - | "s(WildPos + 9)); 
If WildLen > 1 Then Write( 's(wildcen -- 1)); 
Writeln; Writeln; 
. End; . 
PatPtr := PatPtr Next; 


_ Count := Count + 1; 
Until PatPtr = Nil 
'End;.€ Print Patterns } 


Procedure Print Info(Ptr : D ListP); 


Begin € Print_Info } 
Repeat 
With Ptr. wr Do 
Begin 
If D IsBlkd Then 
Case D Kind Of 























D Free : Write('Free space on '); 
D Vol : Write('Volume "); 
D_ ) Temp : Write(*Temporary file on '); 

D Text : Write('Text file on.'); 

D Code : Write(*Code file on '); © 

D Data : Write("Data file on '); 

D SVol : Write(C"SVol file on '); 

End { Cases } 
Else 


Write(' Communications volume '); 
Writeln(D Volume); 
If Want Patterns And (D_VPat <> Nil) Then 
Begin | 
Writeln; 
Writeln(" Volume patterns:'); 
Print_Patterns(D VPat, D_ Volume, Volume); 
End; . 
Writetn(' Unit number ....- «-- ', D_Unit); 
If D_IsBlkd Then 
Begin 
If Not (D Kind: In [CD Vol, D_Free]) Then 
Writeln¢' FILG name .ss.eeeee. Uy D Title); 
If D Kind <> D Free Then 
Begin 
If Want_Patterns And (D_FPat <> Nil) Then 
Begin : 
Writeln(' ' File name patterns:'); 
Print Patterns(D FPat, D Title, Title); 
End; 
With D Date Do 
Writein¢' File date ..... Saabs ps 
Month, '/', Day, '/', Year); 
End; { If D Kind } 
If D Kind = D Vol Then 
Writeln(" Files on volume ... °, BD _NumFiles); 
Writeln(' Starting block was. °, D Start); 
Writeln(' File Length ....... ", D Length); 
End; { If D_IsBlkd } 
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End; { With Ptr } 
Writeln; . 
Write('Type <cr> for rest of. List"); 
Readln; Writeln; 
Ptr := Ptr _ «D NextEntry; 
Until Ptr = Nil 
End; { Print_Info } 


Begin { Listtest } 
Repeat 
Mark (Heap Ptr); 
Select := [1]; 
Writeln('’Directory Lister —"); 
Write(*’Volume and/or file name to atch sit Be 
Readln (Match); 
Write('Return pattern matching information? Cy/n] '); 
Read(Ch); Writeln; 
Want Patterns := Ch In L'y', "YJ; 
If Want Patterns Then 
Result. z= D . ScanTitle(Match, Volume, Title, Typ, Segs); 
Writeln('Types [ y/n] : "ys 
GiveChoice('Directories', CD VolI); 
GiveChotce('Text Files ', (D Text}); 
GiveChoice('Code Files ", (D Code]); 
GiveChoice('Data Files ', ED Data]); 
' 
t 
si F 








¥ 
# 
GiveChoice('Temp Files ‘', CD Temp) ; 
GiveChoice('Free Space ', CD Free]);- 
GiveChoice('SVol Files Cp:  SVOLI); 
Result == D_ DirList (Match, Select, Ptr, Want Patterns); 
Writein; 
If Ptr <> Nit Then 
Print_Info(Ptr) 


Else 
Case Result Of 
D Name Error =: Writetn(’ Error in file name"); 
Dt Off | Line : Writein( Volume off line’); 
D Not Found : Writeln(' File not found"); 
D Other : Writeln(! Miscellaneous error’); 
End; {cases} 
Writeln; 
Repeat 


Write("Continue ?''); 
Read(Ch); Writetn; 
Until Ch In C'n','"N',by','Y¥'I> 
WriteLln; 
Release(Heap Ptr); 
Until Ch In C*n’, "N'I; 
End. { listtest } 
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Function D Change Name 
(D_OLD NAME, D NEW NAME : String; 
D | ) REMOLD : Boolean) : : D Result; 


D Change Name searches for the volume or 
file designated by the file name contained 
in D OLD NAME and changes its name to the 
file name contained in D_ NEW NAME. 


D Change Name only changes one file name at 
a time, and thus doesn't accept file names 
containing wild cards; however, it can be 
combined with other Dir Info and wild card 
routines to create user-defined file name 
changing routines that accept wild cards. 


D Change Name accepts the following 
parameters. 


@ D OLD NAME. A string containing the name 
of the file to be changed. If the file 
name is invalid, D Change Name returns 
D Name Error. Note that wild card 
characters are treated literally. 


@ D NEW NAME. A string containing the 
replacement file name. [If the file name 
is invalid, D Change Name returns 
D Name Error. Note that wild card 
characters are treated literally. 
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@ If DOLD NAME contains an empty file 
title, D Change Name changes the name of 
the volume specified by D OLD NAME to the 
volume name in D NEW ] NAME; any file title 
in D NEW NAME is ignored. If D_ OLD NAME 
contains a nonempty file title, 
D Change Name changes the name of the 
disk file specified by D OLD NAME to the 
file title in D NEW NAME; any volume name 
in D NEW NAME is ignored. If the file ID 
in D NEW NAME is empty, D Change Name 
returns D Name Error. 


@ D REMOLD. If set to TRUE, D REMOLD 
indicates that an existing file or volume 
designated by the file name in D NEW NAME 
may be removed in order to change the 
file name. If set to FALSE, the presence 
of an existing file or volume with the 
same name as D NEW NAME aborts the name 
change, and D | Change _ Name returns 


D ) Exists as a function result. 


@ D Change Name returns a value of type 
D Result. D Change Name can return all 
scalar values defined in D ) Result; the 
values have the following meanings. 


@ D Okay. No error. D OLD NAME was 
found and its name changed. 


@ D Not Found. No such file/volume 


found. No match found for D OLD NAME. 
No change made. 
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@ D Exists. The name change was blocked 
by the presence of an existing file 
with the same name as D NEW NAME. No 
change made. 


@ D Name Error. Illegal file name 
syntax in D OLD NAME or D NEW NAME. 
No change made. 


@ PD Off Line. Volume off-line. The 
volume specified by D OLD NAME wasn't 
on-line. No change made. 


@ PD Other. Unknown. D Change Name 


encountered an error it couldn't 
identify. No change made. 
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Example Program 


The following program demonstrates how 
you might use D Change Name. 


Program chngtest; 
Uses 
(*$UWILD.CODE*) 
wild, 
(*$UDIR. INFO. CODE*) 
DirInfo; 


Var 
RemOld :; Boolean; 
Old, New: String; 
Ch : Char; 
Rslt : D Result; 


Begin { chngtest} 
Writeln('D ChangeName Test — '); 
Repeat 
Writeln; 
Write('Name to change : "); 
Readln(Old); 
Write(’New name : ‘'); 
Read n (New) ; 
Write 'Remove existing files (if any) of that name ? Cy/n] ‘'); 
Read(Ch); Writeln; 
RemOld := Ch In ['y',°Y'J; 
Case D_ChangeName(Old,New,RemOld) Of 




















D Okay = Writeln(¢! - No error’); 
D Off Line : Writeln(* Volume off Line’); 
D Name Error =: Writeltn(’ Error in file name"); 
D Not Found = Writeln(’ File not found"); 
D Other : Writeln(’ Miscellaneous error’); 
End; { cases } 

_ Writeln; 


Write('Continue ? °); 
Read(Ch); Writetn; 
Until ch In C'n', 'N'I; 
End. € chngtest } 
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Wild Card File Name Change 


D Change Name doesn't accept wild card file 
name arguments; however, it can be combined 
with the pattern matching information 
returned by D Dir List to implement a wild 
card, file name changing routine. (Note 
that this routine must use directory locks 
in multi-tasking environments. ) 


For example, assume that you have the 
following files: 


TEST1. TEXT 
TEST12.CODE 
TEST. DATA 


You would like to change them to the 
following names: 


OLDIA.TEXT 
OLD12A.CODE 
OLDA. DATA 


This can be performed by using D Dir List to 
search for the file name ‘'TEST=.='. The 
pattern matching information returned by 
D Dir List can be used to create new file 
titles; in this case, 'TEST' is replaced 
with ‘OLD’, and the first ‘'=' is replaced 
With the concatenation of the pattern 
matched by the '=' and the literal string 
'A'. The part of each file title matched by 
the period and the second '=' wild card is 
unchanged. D Change Name is called with the 
modified file title for each file matched by 
D Dir List. 
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Example Program 


The following program demonstrates how you 
might use D Change Name and D Dir List when 
constructing a specialized file name 
changing utility. The program accepts a 
file name argument containing two '=' wild 
cards; for each file which matches the 
argument, the file title is changed by 
swapping the string patterns matched by the 
two '=' wild cards. 


Program wi ldChange; 


Uses. 
(*$UWILD.CODE*) 
wild, 
(xX$UDIR.INFO.CODE*) 
DirInfo; 


Var 
Heap Ptr =: Integer; 
Typ: D_NameType; 

Segs : Integer; 

Select.: D Choice; 
Volume, Name, Match : String; 
Result : D Result; 

Ch’: Char; 

Ptr. : D-ListP; 





| Procedure GiveChoice(Choice : String; Kind : D Choice); 





Var 
Ch : Char; 

Begin 
Write(' i * Choice,*- 3? ">> 


Read(Ch); WriteLn; Tegee 
. If Ch In Cly', "¥'] Then Select := Select + Kind; 
End; { GiveChoice } 


Procedure Print. Patterns (PatPtr : D PatRecP; ~ 


Comp, Wild : String) 
Var 


Count .: Integer; 
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Begin { Print Patterns } 
Count := 1; 
Writeln({'type <cr> for patterns’); 
Readln; Writeln; 
Repeat 
Writeln('Pattern ‘', BOEED. oS ye 
With PatPtr - Do 
Begin 
Writetn(". Comp : *, Comp); 
If CompLen <> 0 Then 





Write(' ":(CompPos + 9)); 

- If CompLen > 1 Then Write (' *:(CompLen - 1); 
WriteLln; 
Writeln(' Wild = ", Wild); 
WriteC -":QWildPos + 9)); 
If WildLen >.1_Then Write ¢' ":(WildLen — 1)}; 
Writeln;Writeln; . 

End; - 

PatPtr := PatPtr Next; 


Count := Count + 1; 
Untit PatPtr = Nil 
End; { Print Patterns } 


Procedure BE ANTasb ot : D-_ListP; Want_Patterns : Boolean; 
Volume, Name : String); Ng 
Begin { Print_ Info } 
Repeat 
Writeln('MATCHED FILE —'); 
With Ptr Do 
Begin 
Write(D Volume, ':'); 
If D_ IsBLkd-Then 
If ~Length(p Title) > 0 Then 
Write(D Title); 
Writeln; 
If Want Patterns And (D VPat <> Nil) Then 
Begin 3 
Writeln: 
Writeln(’ Volume patterns:'); 
Print _Patterns(D ) VPat, D Volume, Volume); 
End; 
If D_IsBlkd Then 
If Want Patterns And (D FPat <> RIO. Then 


Begin. , 
Writeln¢' File name patterns:'); 
Print_Patterns(D ) FPat, D Title, Name) ; 

End; 
End; { With Ptr . ’ 3 


Writeln; 
Write(" Type <cr> for rest of List! >; 
Readin; Writetn; 
Ptr <= Ptr -D NextEntry; 
Until Ptr = Nil | me 
End; { Print_Info } 





4-44 


File Management Units 


Procedure Change(Ptr : D ListP; Name : String); 
Var 

I, Posi, Len1, Pos2, Len2, Last_Pos, 

Mid Pos, Last Equal : IOP EQECs 

Pati, Pat2, Title, New : string; 


Procedure Find Equal(D Title, Name : String; 
Var PatPtr : D_PatRecP; 


Var Pat : String; 
Var Pos, Len : Integer); 


Begin { Find Equal } 


While (NameCPatPtr »WildPos] <> '=")- And 
(PatPtr «Next <> NIL) Do 
PatPtr 32= PatPtr -Next; 
with PatPtr Do | 
Begin 


If CompLen = 0 Then Pat := '' 
Else Pat := Copy(D Title, CompPos, CompLen); 
Pos := CompPos; 
Len := CompLen; 
End; 
End; { Find Equal } 


Begin £ Change } 
With Ptr Do 
Begin 
Find Equal(bD_ Title, Name, D_FPat, Pat1, Posi, Len1); 
If D FPat <> Nil Then 
Begin 
D_FPat := D FPat ‘Next; 
Find Equal(D Title, Name, D FPat, Pat2, Pos2, Len2); 
New := D Title; 
Last Pos := Posé2 + Len2; 
Mid Pos := Post + Len2; 
Last_Equal := Last_Pos - Len‘; 
For I := Post To Mid | Pos - 1 Do { Tat ‘=! 3} 
NewfI] := PateCI - - Post + 11; 
For I := Mid Pos To Last Equal - 1 Do 
NewlfI] := BD TitleCI - Len2 + Lenij; 
For I := Eee tee To Last_Pos - 1 Do ¢ 2nd ‘=" } 
NewfI) := Pat1CI - Last_Equal + 1]; 
New = := Concat (D | Volume, me, New) ; 
Title := Concat(b ) Volume, of oy D Title); 
Result := D . ChangeName(Title, New, True); 
write(Title, ‘=>', New); 
Case Result of 
-D_Name Error : Write(" Error in file name"); 
D Off | Line : EEE, Volume off Line"); 
D | . Not. Found.: Write(' file not found"); 
D . Other : Write Miscellaneous error'); 
End; {cases}. 
unstain® 
End; { if D_FPat } 
End; { with } 
End; { Change } 
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Function Display(S, Match, Volume, Name : String; 
Select : D Choice) : D ListP; 
Var a = 
Ch : Char; 
‘Ptr .: D_ListP; 
Want. Patterns : Boolean; 
Result : 0 Result; 





Begin { Display } 
Writeln; Writeln(S); 

; Write" Display pattern BERS sd information ? '); 
Read(Ch); WriteLln; 


Want_Patterns a= C8) In Liye ys 
Result := D  DirList (Match, alec. Ptr, True); 
If Ptr <> Nil Then 

Print_Info(Ptr, Want_Patterns, Volume, Name). 


Else 
Case Result Of 
D Name Error =: Writeln(? © Error in file name"); 
D . OFF Line ¢ Writeln (¢' Volume off Line'); 
D Not | Found : Writeln(¢’ File not found'); 
D Other : Writeln¢' Miscellaneous error'); 


End; {cases} 
Display := Ptr; 
End; { Display } 


Begin {€ WildChange } 





Writeln; 
Repeat 
Mark (Heap Ptr); 
Select := (J; 


Write('File title to maven ls contain two 't="'")s "); 
Readln (Match); 
Result :=.D  ScanTitLe(match, Volume. Name, Typ, Segs); 
Writeln('Types £ y/n 1 : ‘ys 
GiveChoice("Directories’, CD _Vol]); 
GiveChoice('Text Files ', (D Text); 
GiveChoice(’Code Files ', [D Code]); 
GiveChoice("Data Files ', (Cb Datal); 
GiveChoice('SVol Files ', CD SVol]); 
Ptr z= Display('Old Files :', Match, Volume, Name, Select); 
If Ptr <> Nil Then | 


“Begin 
Repeat | 
‘Change (Ptr, Name); : 
Ptr z= Ptr «D_NextEntry; 


Until Ptr = Nil; 
WriteC'’Redisplay files? "); 
Read(Ch); vriteto; 
If ¢ Ch In. Cty *¥'] Then 
Ptr := Display¢* New. Files oe Match, 
Volume, Name, Select); 





4-46 


File Management Units 





Function D Change Date 
(D NAME : String; 
D NEWDATE : D DateRec; 
D SELECT : D Choice) : D Result; 


D Change Date changes the file date of 
volumes and files whose names match the file 
name argument contained in  D NAME. 
D Change Date accepts wild cards in its file 
name argument. If a volume date is changed, 
only the disk is updated. The disk must be 
rebooted if the new date is to be used. To 
change the internal date, which will appear 
when D(ate is used in the filer, use the 
date access procedures within the SYS.INFO 
unit. 


D Change Date accepts the following 
parameters. 


@ D NAME. A string which contains a valid 


file name. The file name may contain 
wild cards. 
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@ D NEWDATE. A record of type D DateRec 
which contains the new date. A year 
value of 100 isn't accepted = by 
D Change Date in a new date. 


@ D SELECT. A set of file and/or volume. 
All scalar types except D Free and D Temp 
apply to D Change Date. Disk free spaces 
identified by the D Free scalar don't 
contain file dates. Temporary status for 
files is specified by a special value in 
the file date field. Thus, D Free and 
D Temp are ignored if they are included 
in D SELECT. 


D Change Date returns a value of type 
D Result. D Change Date can return all 
scalar values defined in D Result except 
D Exists; the values are described in the 
following items. 


@ PD Okay. No error. D_NAME was found, and 
D NEWDATE was written to the directory 
for the specified file or disk volume. 


@ D Not Found. No such file/volume found. 


No match found for D NAME. No change 
made. 


@ D Name Error. Illegal syntax in D NAME. 
No change made. 
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@ D Off Line. Volume off-line. The volume 


specified by D NAME wasn't on-line. No 
change made. This error occurs only if 
the volume ID in D NAME specifies a 
single volume which is off-line. If the 
volume name in D NAME contains wild cards 
and doesn't match any on-line volumes, 
D Change Date returns D Not Found. 


D Other. Unknown error. No change made. 
D Change Date encountered an unidentified 
error which prevented successful 
completion of the operation. 
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Example Program 


The following program demonstrates the 
of D Change Date. 


_ Program Date _Test; 


Uses 
(*$UWLLD.CODE*) 
wild, — 
‘(*$UDIR. INFO. CODE*) 
DiriInfo; — 

Var EOE 
Result : D Result; 
Ch : Char; 





M, D,-Y ..:. Integer; 
NewDate : D_DateRec; 
Select~ .-: D. Choice; 
FileName -: String; © 


Procedure GiveChoice(Choice + String; Kind : b_ Choice); 
Var ; ma 
Chi 2.Chane 
Begin us 
WriteC’ ', Ghoice,' ? oe 
-Read(Ch); Writetn; cf ; a 5 ; 
If ch In Cry’, "¥'d Then Select a= Select + Kind; 
End; Givechoice } *, 








“Begin { Date_ Test 5 
Select r= (1; 
Writeln('bd _ChangeDate Test —"); 
Repeat 
Writetn; 
 WriteC'’File to change.:_'); Readin¢ FileName) j 
Writeln('Types. C-y/n 7 : ty> 
GiveChoice(*Directories’, [D_ voll); 
GiveChoice(’Text Files ", ED Text); 
-GiveChoite('Code Files ', [CD Codel); 
GiveChoice('Data Files *, CD Datal); 
GiveChoicet'SVol Files ', (CD SVoll); 
GiveChoice("SVol. Files", Cp. SVol]); 
Writeln('New date : '); 
Write('Month CT - 123.: *2; Readin(M): 
Write('’Day . [1 = 31]-: ')3 Readin(D); 
Write('Year. [0 - 99] "); -Readtn(Y); 
With NewDate Do : - 
Begin 
Month 
Day. 
Year = eal 
. End; ©. with Newbate > 
Writetlns 
Result = D - ChangeDate (FileName, Newbate, Select); 








M 
D; 
Y 


ws ‘Se NS 
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Function D Rem Files 
(D NAME : String; 
D_SELECT : D Choice) : D Result; 


The D Rem Files function removes file 
objects whose names match the file name 
argument contained in D NAME and types match 
the elements included in D SELECT. The file 
name argument may contain wild cards. Disk 
files are permanently deleted from their 
directories. Volumes are taken off-line, 
but not altered in any way; off-line disk 
volumes may be brought back on-line merely 
by referencing them, while off-line serial 
volumes remain inaccessible until the system 
is reinitialized. 


D Rem Files accepts the following 
parameters. 


@ D NAME. A string containing the name of 
the file(s) or volume(s) to be removed. 


@ D SELECT. A set of file objects to be 
removed. The definition of the set is as 
follows: 


D NameType = (D Vol, D Code, D Text, 


D Data, D SVol, 
D temp, D Free); 
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D_ Choice = Set Of D NameType; 


All scalar types except D Free apply to 
D Rem Files. Disk free space can't be 
removed from the directory; thus, D Free is 
ignored if it is included in D SELECT. 


D Rem Files returns a value of type 
D ) Result. D Rem Files can return all scalar 
values defined in D Result except D Exists; 
the values have the following meanings: 


@ D Okay. No error. D NAME was found. If 
D Vol is included in D SELECT, and a 
volume matches the file name argument in 
D NAME, the volume is taken off-line. If 
D Text, DCode, D Data, D SVol, or D Temp 
are included in D SELECT, disk files of 
those types which match D NAME are 
deleted from their directories. 


@ D Not Found. No such file/volume found. 
No match found for D ) NAME. No change 
made. 


@ D Name Error. Illegal file name syntax 
in D NAME. No change made. 


@ D Off Line. Volume off-line. The volume 
specified by D NAME wasn't on-line. No 
change made. This error occurs only if 
the volume ID in D NAME specifies a 
Single volume which is off-line. If the 
volume ID in D NAME contains wild cards, 
but doesn't match any on-line volume, 
D Rem Files returns D Not Found. 
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@ PD Other. Unknown error. No change made. 
D Rem Files encountered an unidentified 
error which prevented successful 
completion of the operation. 


Example Program 


Program Rem Test; 


Uses 
C*xSUWILD.CODE*) 
wild, 
(*$UDIR.INFO.CODE*) 
Dirinfo; 

Var 
Result : D_ Result; 
Select : D Choice; 


Ch : Char; 
Remfile =: String; 


Procedure GiveChoice(Choice : String; Kind : D Choice); 
Ch : Char; 


Begin 

Write(' ', Choice,’ ? '); 

Read(Ch); Writeln; 

If Ch In C'y', "¥'] Then Select := Select + Kind; 
End; € GiveChoice } 





Begin { Rem Test } 
Select := (CJ; 
Writeln("D Rem Files Test —'); 
Repeat 
Write('File(s) to remove : '")> 
Readln(Remfile); 
Writeln('Types C y/n J] : "); 
GiveChoice(*Directories', [D Vol]); 
GiveChoice('Temp Files ', CD _Temp]); 
GiveChoice('Text Files *, (Db Text); 
GiveChoice('Code Files ', CD Coded); 
a 
ra 
nea 








GiveChoice("Data Files CD Datal); 

GiveChoice('SVol Files Co SVol]); 

Result. := D_ Rem | Files (Remfite, Select); 

Case Result Of 
D Okay : Writeln('files ennveniNs 
D Name Error : Writeln('error in file name"); 
‘D Off Line : Writeln('volume off Line"); 
D Not Found : Writeln("fite not found"); 
D Other - Writeln( miscellaneous error’); 

End; { cases } 

Writeln; 

WriteC’Continue ? "); 

Read(Ch); Writeln; 

Until Cth In C'n','N'I; 
End. { Rem Test } 
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Procedure D_ Lock 


D Lock grants exclusive directory access 
rights to the task that executes it; 
however, a task may have to wait until 
another task releases the directory lock 
before it can continue execution past its 
call to D Lock. 


NOTE: D Lock calls should always be matched 
with D Release calls to prevent system 
deadlocks. 


The Dir Info routines D Lock and D Release 
are provided for use in multi-tasking 
environments. When used properly, they 
ensure mutually exclusive access’ to 
directory information. 


Procedure D Release 


D Release releases exclusive access rights 
to the directory. Tasks already waiting for 
directory access are automatically awakened 
when the directory becomes available by a 
call to D Release. 
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Example Program 


The following program demonstrates 


of D Lock and D Release. 


Program Locktest; 
Uses 
(x$UWILD.CODE*) 
wild, 
C*$UDIR. INFO. CODE*) 
DirInfo; - 


Const - 
‘Stack Size = 2000; 
Var 
Pid : Processid; 
Old, 
New : String; 
Date :-D_ DateRec; 
M, D, Y : Integer; .. 
Ch : Char; 


Process Change And Check(Old, New:. String; 


Var 


Result : BI Result; 


Begin { Change And _| check } 


the use 


“Date : D DateRec); 


{ beginning of critical section } 


D. Lock; .. 
Result := D ChangeDate(Old, Bates CD Vot..D_ SVol]); 
“If Result = D . Okay Then 

Result := D )-ChangeName (Old, New, True); 


D Release; 
End; ¢ Change_And_ Check ¥ 
Begin { LockTest } 
Repeat 
Write('Old file name: 
ReadLn(OLld); 
Write('New file name: ‘); 


fi 


Readin(New) ; 
Writeln('New date:'); 
Write C' Month: '); 
Readin(™); « 
Write <’ Day: "); 
Readln{D);- 
Write(! Year: ");. 
Readin(Y);- 
With Date Do 
Begin: 
Month :=. M; 
Day = D; 
Year := Y; 
End; 


4-95 


{ end of critical section } 


r1lie Management Units 





4-56 


File Management Units 


WILD CARDS (WILD) 


The unit WILD provides a wild card convention 
for pattern matching of string variables. Wild 
cards are special character sequences in a 
character string; they are named wild cards 
because of their ability to match whole classes 
of character sequences rather than a _ single 
character sequence. For instance, the string 
"a=" matches all character strings starting with 
the letter "a" because ( = ) is defined as a 
wild card that matches any character sequence. 


Wild cards are useful in pattern matching 
situations where many character strings are to 
be matched with a single request. The p-System 
filer uses a set of wild card facilities in its 
directory operations. Examples are given in the 
Operating System Reference Manual that describes 
the filer operation. Because of the extra 
functions provided by this UNIT, there isn't a 
direct correspondence between the filer and this 
UNIT. Where there are differences in the use of 
characters, these are described. 
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Special Wild Card Characters 


The following characters are defined as 
Special characters: 


question mark 
equal sign 
braces 

comma 

hyphen 

tilde 

percent sign % 


“~~ on 


and } 


vi ~ 


Special characters may only be used as parts 
of wild cards. However, a literal occurrence 
of a special character can be represented by a 
two character sequence consisting of a percent 
sign followed by the special character. A 
percent sign indicates that the following 
character is to appear literally in the 
character string; for instance, "xx%=yy" is 
treated as the literal character string 
"xx=yy" rather than a wild card string. 


Examples of percent sign in wild cards: 


"a b%?def" matches "ab?def" 
"“abla-z, %=}de%%f" matches "ap=de%f" 
"abk— def" matches "ab—def" 
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Question Mark Wild Card 


A question mark matches any single 


character. In the filer, the ( ? ) is 
treated as an interactive query of an ( = ) 
Wild card. This is one of the major 


differences in use of characters between 
this UNIT and the filer. 


Examples of ( ? ) wild card: 


Pattern: "ab?def" 

Matches: "abbdef" 
"abrdef" 

Nonmatch: "abdef" 
"ab jkdef" 
"“ahef "1 


Equal Sign Wild Card 


An equal sign matches any sequence of 
characters, including the empty sequence. 
This is the same as the filer except that 


more than one ( = ) can appear in a wild 
card string. 
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Examples of ( = ) wild card: 


Pattern: "ab=def=" 

Matches: “abcdefe" 
"abdef" 
"abecedef" 

Nonmatches: "abcef" 


Subrange Wild Card 


The subrange wild card matches a_ single 
character from the character set specified 
in the subrange. The special characters, 
comma, hyphen, tilde, and braces, are used 
to construct subrange wild cards. 


A subrange wild card consists of a character 
set delimited by braces. A character set 
consists of a list of character-items 
separated by commas. 


A character-item is either a character or a 
character range (two characters separated by 
a hyphen). A character range implicitly 
specifies all characters lying between the 
two characters. (Consult an ASCII table to 
determine the ordering of characters. ) 
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Character-items preceded by tildes are 
called negated-items and are specifically 
excluded from the character set. A 
character range proceeded by a tilde is 
entirely excluded from the character set. 
The list of character items is evaluated 
left-to-right. Characters specified by 
non-negated items are included into the set; 
characters specified by negated items are 
excluded from the set. Thus, a character 
matches the subrange wild card if it matches 
one of the non-negated items, but doesn't 
match any of the negated choices. For 
example, the subrange "{a-z,"r}" represents 
the set of characters from "a" to "z," 
excluding "r." 


NOTE: Blank characters within subrange wild 
cards are ignored. Wild card characters can 
be specified in character sets with the 
percent sign notation described in the 
preceding paragraphs. 


Examples of subrange wild cards: 
{a,b,c} 


{a-d, Jj ,W-Z } 
{ a-z, Jj, X-¥y } 
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syntax for subrange wild card: 


wild-card = "{" item-list "}" 
itemlist = item < "," item > 
item = [7] char-item 
char-item= char / range 
range = char "-" char 

char = an ASCII character 


Examples of subrange wild card: 


Pattern: "ab{a-r, ~j, “k}def" 
Matches: "abbdef" 

"abrdef" 
Nonmatches: "abjdef" 

"abkdef" 

"abzdef" 
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Function D Wild Match 
(WILD, COMP: String; 
Var PPTR : D PatRecP; 
PINFO : Boolean) : Boolean; 


D Wild Match serves as a general purpose 
pattern matcher for string variables using 
the wild card conventions described above. 
The two main parameters are a wild card 
string, WILD, and a literal string, COMP. 
D Wild Match determines whether the literal 
string matches the wild card string. If the 
strings match, D Wild Match returns true; 
otherwise, it returns false. If PINFO is 
set to true, D Wild Match returns 
information (accessed through PPTR) that 
describes how the strings were matched. 


D Wild Match Parameters 


D 


) Wild Match accepts the following parameters: 


WILD. A string which may contain wild 
cards. 


COMP. A literal text string. 
PINFO. A Boolean. If set to TRUE, PINFO 


requests that pattern matching information 
be returned. 
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@ pprer. Pointer <Of, type Dp Pathecr, 
Depending on the value passed in PINFO, 
D Wild Match either sets PPTR to NIL or 
points it at a linked list of records 
containing pattern matching information. 


D Wild Match Pattern Matching Info 


If PINFO is set to TRUE, D Wild Match returns 
pattern matching information in PPTR. PPTR is 
a pointer (of type D PatRecP) to a linked list 
of records which contain the starting 
positions and lengths of corresponding 
character patterns in WILD and COMP. 


D: Pat. nheeP is defined as follows: 


Db. PatnecP: «= “DD. Pathee: 

D PatRec = Record 
CompPos , 
CompLen, 
WildPos, 


Wilden: Integer; 
Next, Di rarnkecr ; 
Bnd 5. 1. D> PatRee: 2} 


CompPos and WildPos are the starting positions 
of corresponding character patterns in COMP 
and WILD, respectively. CompLen and WildLen 
are the pattern lengths. Next points to the 
next pattern record in the list; it is set to 
NIL in the last pattern record. The patterns 
occur in the list in the order in which they 
were matched in the strings. 
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If the strings don't match, or the list wasn't 
requested (that is, PINFO is set to false), 
PPTR is set to NIL. 


Example of pattern record list: 


WILD contains: '=abf{a-m}=f?' 
COMP contains: 'abcdefg' 


If PINFO is set to true, pattern record list 
returned is: 


Ls 


- WildPos 


WildPos = 1, WildLen = 1 
CompPos = 1, CompLen = 0 
('=' matches the empty string) 


WildPos = 2, WildLen = 2 
CompPos = 1, ComplLen = 2 
('ab' matches ‘ab') 


WildPos = 4, WildLen = 5 
CompPos = 3, CompLen = 1 
('{a-m}' matches 'c') 


lI 


9, WildLen = 1 
CompPos = 4, CompLen = 2 
('=' matches ‘'de') 


» WildPos = 10, WildLen = 1 


CompPos = 6, CompLen = 1 
('f' matches ‘f') 


WildPos = 11, WildLen = 1 
CompPos = 7, Complen = 1 
('?' matches 'g') 
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NOTE: When the ( = ) wild card in WILD 
matches an empty string in COMP, CompLen is 
set to 0 and CompPos is set to the position of 
the next pattern in COMP (that is, the 
position where a nonempty pattern would have 
occurred). Be sure to check the validity of 
CompPos indices before using them to reference 
characters in COMP; otherwise, range errors 
may occur. 
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Example Program 


The following program is an example of a 
string comparison routine that uses 
D Wild Match. The program reads two strings 
and prints the result of the comparison; if 
requested, it also prints information 
describing how the patterns matched. 


Program Wild Test; 


Uses (*$UWILD.CODE*) 
wild; 


Var 
W, C : String; 
Ch : Char; 
PatPtr-: D PatRecP; 
Want_Patterns : Boolean; 


Procedure Print Patterns(PatPtr : D_PatRecP; 
C, W: String); 
Var 


Count : Integer; 


Begin { Print Patterns } 

'. Writein('type <cr> for patterns"); 
Readln; Writeln; 
Count := 17 














Repeat : 
Writeln('’Pattern *, Count, * :'); 
With PatPtr ' Do 
Begin 
Writetn(' Comp : ', ©); 
If CompLen <> 0 Then Write(' ':(CompPos + 9)); 
If CompLen > 1 Then Write(' *»(CompLen -.1)); 
Writeln; 
Writeln(* Wild: ', W); 
Write(' "s(WildPos + 9)); 
If WildLen > 1 Then Write(' '-(WildLen - 1)); 
Writeln; Writeln; 
End; . 
PatPtr :s= PatPtr «Next; 


Count := Count + 1; 
Until PatPtr = Nil; 
End; { Print Patterns } 


Begin { Wild Test } 
Repeat 
Writetn('—WildCard Check—"); 
WriteC'Wild Card String =: '); 
Readln(wW); 
Write('Comparison String : '); 
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SYSTEM INFORMATION 


Unit SYS.INFO is an easy way to access some of 
the system global information. SYS.INFO uses 
KERNEL.CODE in its implementation section. 
Although it is possible to access KERNEL.CODE 
directly, there are many variables that are 
normally not needed. If you require a different 
set, then another unit similar to this one can 
be easily constructed for the particular 
situation. 


In order to distinguish the variables defined by 
this unit, they have been prefixed with SI. 
Here are the SYS.INFO routines: 
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Work Code File Name: 


Procedure SI Code Vid 
(Var SI Vol : String); 


Procedure SI Code Tid 
(Var SI Title : String); 


The preceding procedures return the volume name 


(Si Vol). -and- ‘The: ‘tile. name. Csi Title) sof the 
system work code file. 


Work Text File Name: 


Procedure SI Text Vid 
(Var SI Vol : String); 


Procedure SI Text Tid 
(Var SI Title : String); 


The preceding procedures return the volume name 


(OL Vol) and: the file name (ol Title) or “tne 
system work text file. 


System Volume: 


Function SI Sys Unit : Integer; 
The SI Sys Unit function returns an integer 


function result. The device number of the drive 
containing the system volume is returned. 
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Procedure SI Get_Sys Vol 
(Var SI Vol : String); 


The preceding procedure returns the volume name 
(SI Vol) of the current system volume. 


Prefixed Volume Name: 


Procedure SI Get Pref Vol 
(Var SI Vol : String); 


Procedure SI Set Pref Vol 
(SI Vol : String); 


The preceding procedures allow the current 
prefix volume to be read and set. 


4—70 


File Management Units 


System Date: 


Procedure SI Get Date 
(Var SI Date : SI Date Rec); 


Procedure SI Set Date 
(Var SI Date : SI Date Rec); 


The SI Get Date and SI Set Date procedures 
access and modify the system date. The date is 
passed as a record of type SI Date Rec. 
Changing the date won't change the date on the 
system disk. It will only change the date 
internally in the operating system. To change 
the date on the disk, use function D Change Date 
within the DIR.INFO unit. 


SI Date Rec = Packed Record 
Month : 0..12; 


Day : 0.2.31; 
Year : 0..99; 
End ; 


This record is used in the operating system to 
store dates. It is a packed record and only 
requires 16 bits. All date variables use this 
format. 
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Example Program 


Program Sys Test; 
Uses {$USys.Info.Code} Sys_Info; 


Var 
Ch. s. Char; 
Date : SI_ Date Rec; 





Vol, 
Title : String; 
Begin 


SI_Code Vid (Vol); 
SI_Code Tid (Title); 
If Length (Title) <> 0 Then 
Writeln ('The Work Codefile is ', Vol, ‘:', Title) 
Else 
Writeln (‘There is no Work Codefile.'); 
SI_Text_Vid (Vol); 
SI "Text Tid (Title); 
If | Length (Title) <> 0 Then 
Writeln ("The Work Textfile is *, Vol, ':', Title) 
Else 
Writeln (*There is no Work Textfile.'); 


Writetn:; 
SI_Get_ Sys Vol (Vol); 

' Writeln ('The System was booted on volume ', Vol, 
*s on device ', SI_Sys. Unit); 
SI Get _Pref Vol (Vol); 


_ Writeln; 
Writeln ("The Prefix volume is *, Vol, ':"'); 
Write ¢' ‘New’ Prefix: '); 
Readin (Vol); 
Delete (Vol, Pos (':', Vol), 1); 
If Length (VoL) In £1..7] Then 
Begin 
SI_Set_Pref Vol (Vol); 
SI "Get Pref | Vol (VoL) + 
Writeln ('The Prefix volume is CeO gta pie 
End fof If} 
Else 
Writeln ('No change made") y. 





Writetn; 
SI Get Date (Date); 
Writeln (’The current date is * ,° 
Date.Month, -Date.Day, -Date.Year); 
Repeat 
Write ('Set for tomorrow's date ? "); 
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Read (Ch); yam 
UntaUlCh in: os ye inte tN 
Writeln; 
Tf’ ChtIn- C*y",..°¥" 1 then 
Begin — 
Date.Day := Date.Day + 1; 
If (Date.Month In (1, 3, 5, 7, 8, 10, 12]) And (Date.Day = 32) Or 
(Date.Month In (4, °6, 9, 111) And (Date .Day = 31) Or 
(Date.Month = 2) And (Date.Day = 29) Then 
. Begin 
Date.Day := 1; . 2 
If Date.Month = 12 Then 
Begin 
Date.Year := Date.Year + 1; 
Date.Month := 1; 
End fof If =12} 
‘Else 
Date.Month := Date.Month + 1; 
End fof If Date.Month}; 
SI_Set Date (Date); 
_. SI_Get_ Date (Date); 
“- Writetn ("The new date is ', 
: Date.Month, -Date.Day, -Date.Year); 





End {of If Ch} 
‘Else hens 
Writeln ("No change made"); 
End {of Sys Test}. 
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FILE INFORMATION 


This unit provides an easy way to access 
information in the file information block (fib). 
It uses the system globals from KERNEL.CODE. 
Although it is possible for you to access the 
global data, it 1S easier to use this unit. In 
order to distinguish the variable names in this 
unit, they have all been prefixed with an 'F'. 


Type F File Type = file; 


Because of a Pascal language restriction, it is 
necessary to declare files of type (f file type) 
that are to be passed on as parameters to these 
procedures and functions. 


Function F Open 
(var fid: F File Type):boolean; 


This function should be called before any of the 
following are used. This enables a check to be 
made on the status of a file. The function 
returns true if the file is open and false if 
isn't open. The following functions won't give 
the correct values if the file isn't open. 
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Function F Length 
(Var Fid : F File Type) : Integer; 


Returns the length (in blocks) of the file 
attached to the Fid identifier. If the file 
isn't opened, the result is returned as zero. 
This only has meaning for files on storage 
volumes as the value returned is the number of 
blocks allocated to the file. 


Function F Unit Number 
(Var Fid : F File Type) : integer; 


Returns the device number of the storage volume 
containing the file attached to the Fid 
identifier. If there is no file opened to the 
Fid, the function result is zero. 


Procedure F Volume 
(Var Fid : F File Type; 
Var File Volume : String); 


Returns the name of the volume containing the 
file attached to the Fid identifier. If the 
external file lacks a defined volume name, 
F Volume returns a volume ID constructed from a 
device number (such as #4:). If there is no 
file opened to the Fid, the File Volume is set 
to a null string. 
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Procedure F File Title 
(Var Fid : F File Type; 
Var File Title : String); 


Returns the title (with suffix) of the file 
attached to the Fid identifier. If there is no 
file opened to Fid, or if the external file is a 
volume, then the File Title is set to a null 
string. - 


Function F Start 
(Var Fid : F File Type) : integer; 


Returns the block number of the first block of 
the file attached to the Fid identifier. This 
only has meaning for files on storage volumes. 
If there is no file opened to Fid, the function 
result is returned is zero. 


Function F is Blocked 
(Var Fid: F File Type) : Boolean; 


Returns a boolean that is TRUE if the file 
attached to the Fid identifier is located on a 
storage volume (or block-structured device). If 
there is no file opened for the Fid or if the 
device isn't a storage volume, the function 
result is set to false. 
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Procedure F Date 
(Var Fid : F File Type; 
Var File Date : F Date Rec); 


Returns a record indicating the last access date 
for the file attached to the Fid identifier. If 
there is no file opened to Fid, the File Date is 


unchanged. The definition of F Date Rec type 
is: 


F Date. Rec: = Packed: Record 
Month : 0..12; 


Day: =: Ose51., 
Year : O..100; 
Bind ; 
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DEBUGGING 


AND ANALYSIS 


Debugging and Analysis 


INTRODUCTION 


This chapter describes the debugger and _ the 
performance monitor. The debugger is a tool for 
correcting errors in programs that you develop. 
The performance monitor is a mechanism that may 
assist you in gathering program (or operating 
system) performance information. 


DEBUGGER 


The symbolic debugger is a tool for locating and 
correcting errors in compiled programs. You can 
call it from the Command menu. It can also be 
selected while a program is running (when a 
break point is encountered). Using the symbolic 
debugger, you may display and alter memory, 
Single-step p-code, and display and traverse 
markstack chains. 


To use the debugger effectively, you must be 
familiar with the p-machine architecture and 
understand the p-code operators, stack usage, 
variable and parameter allocation, and so on. 
These topics are discussed in the Internal 
Architecture Reference Manual. 


O-3 


Debugging and Analysis 


You may have to use the Library utility to place 
the debugger into SYSTEM.PASCAL. If this is the 
case with your p-System package, you should 
consult the "Configuration Notes Appendix" to 


the Operating System Reference Manual. 


Using the Debugger 


There are no menus explaining the debugger 
commands because they would detract from any 
information displayed by the program being 
debugged. However, when a command is entered, 
the system displays several short prompts that 
may ask for information. 


Many of the debugger commands require two 
characters (such as 'LP' for L(ist P(code, or 
'LR' for L(ist R(egister). To exit the 
program after entering the first character, 
press <space> to recall the main mode of the 
debugger. 


A current compiled listing of the program is a 
helpful debugging tool. It helps you 
determine p-code offsets and similar 
information. 


The debugger is a low-level tool, and as such, 
you must use it with caution. If you use the 
debugger incorrectly, the p-System can fail. 
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Entering and Exiting 


Press 'D' to call the debugger from the 
Command menu. If you enter the debugger in 
a fresh state, the system displays’ the 
following prompts. 
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A fresh state means that the debugger wasn't 
previously active, and no break points are 
currently enabled. If you enter the 
debugger in a nonfresh state, only the left 
parenthesis "(" appears. 


Exit the debugger by pressing 'Q' to select 


Q(uit, ‘'R' to select R(esume, or 'S' to 
select S(tep. The Q(uit option disables the 
debugger. If the debugger is selected 


again, it returns in a fresh state. The 
R(esume option won't disable the debugger 
and execution continues from where it left 
off. The debugger is still active; and if 
it is called again, it is in a nonfresh 
state. The S(tep option executes a single 
p-code and automatically again calls the 
debugger in a nonfresh state. 


If a program iS running under the debugger's 
RCesume command, it may force a return to 
the debugger by calling the HALT intrinsic. 
In fact, any run-time error causes a return 
to the debugger, if the debugger is active 
while the program is running. 
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You may memlock or memswap the debugger (see 
the descriptions of those intrinsics) by 
using the M(emory command at the outer 
level. 'ML' memlocks and 'MS' memswaps the 
debugger. 


Using Break Points 


To enter the debugger while a program is 
running, but not alter the program's code, 
use the debugger to set break points. Press 
"B' to call the B(reakpoint option and then 
use either the S(et, Remove, or L(ist 
command. To set a break point, press S(et 
after pressing B(reakpoint. There are, at 
most, five break points numbered O through 
4. The system displays four prompts asking 
for information. The first prompt is: 





Enter a digit in the range O through 4 and 
press <space>. The next prompt is: 





Enter the name of the desired segment and 
press <space>. The next prompt is: 
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Enter the number of the desired procedure 
and press <space>. The final prompt is: 


Enter the desired offset within the 
procedure and press <space>. The system 
sets a break point; and if that segment, 
procedure, and offset are encountered while 
resuming execution, the debugger is 
automatically called again. 


Use a compiled listing of the program to 
determine the location of the break point. 
If no compiled listing is available, use the 
text file viewing facility. 


To remove a break point, press B(reakpoint; 
then press R(emove. The system displays the 
following prompt: 


To remove a break point, enter its number; 
then press <space>. 


To list the current break points, press 
B(reakpoint and then press L(ist. 
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Viewing and Altering Variables 


The V(ar command allows the system to 
display data segment memory. It is another 
two-character command that must be followed 
by G(lobal, L(ocal, I(ntermediate, 
E(xtended, or P(rocedure. If G(lobal or 
L(ocal is selected, the system displays the 
following prompt: 


Enter the desired offset into the data 
segment. 





If I(ntermediate is selected, 
displays the following prompt: 


the system 





Enter the appropriate delta lex level for 
the desired intermediate variable. 












xtende is selected, the 


displays the following prompt: 


system 





Enter the appropriate segment number and 
offset number for the desired extended 
variable. 
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If P(rocedure is selected, the system may 
display an offset within a specified 
procedure. The following prompts are 
displayed in sequence. 





When any of these options are used, the 
system displays a prompt similar to the 
following line: 





This example is a portion of the local 
activation record for segment INIT, 
procedure 1, variable offset 1, at absolute 
hexadecimal location 2C1A. Following this, 
eight bytes are displayed, first in 
HEXADECIMAIL and then in ASCII (a dash "-" 
indicates that the character isn't a 
printable ASCII character). 


To view surrounding portions of memory, 
press V(ar. After a line has been displayed 
by the V(ar command, a ‘t' or ‘'-' may be 
entered. This displays the succeeding or 
preceding eight bytes of memory. 
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The eight bytes that are currently displayed 
may be altered. If a '/' is pressed, then 
the line may be altered in hexadecimal mode. 
If a "\' is pressed, then the line may be 
altered in ASCII mode. When altering in 
hexadecimal mode, any characters that are to 
be left unchanged may be skipped by pressing 
<space>. In the ASCII mode, any characters 
to be left unchanged may be skipped by 
pressing <return>. 


It is possible to change the frame of 
reference from which the global, local, and 
intermediate variables are viewed. This can 
be done by using the C(hain command. Press 
'C'. The Ucp, Dt(own and L(ist options are 
available. If ‘'L' is pressed, ali of the 
currently existing mark stack control words 
are displayed, with the most recently 
created one first. An entry in the list 
resembles the following line. 





= ery Pe ye y= 4 ee stept) pigs oneghitie tears 7, Dien a oe OS Re an ae ab x yee Ate 
(ms) S=HEAPOPS P#3 0423 -msstat=347C. msdyn=FOAO: msipc=01DA_ msenv=FEE8 


This corresponds to a mark stack control 
word with the indicated static link 
(msstat), dynamic link (msdyn), interpreter 
program counter (msipc), and erec pointer 
(msenv). The indicated segment (HEAPOPS), 
procedure (#3), and offset (#23) are the 
return point for the procedure call which 
created the MSCW. 
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If the U(p or Down options are used, the 
frame of reference moves up or down one link 
and the frame of reference for variable 
listings (using the '‘'V' command) changes 
accordingly. 


Viewing Text Files 


To view a text file from the debugger, press 
'F’ to call the F(ile command. The system 
displays the following prompt: 





Enter the name of the text file to be viewed 
followed by <space>. The .TEXT portion of 
the file name is optional. Then enter the 
first and last line numbers that delimit the 
portion of text that you wish to view. This 
command lists as many lines as possible in 
the window from first line to last line of 
the indicated file. 


The F(ile command is useful for debugging 
(especially using symbolic debugging) when a 
hard copy of the relevant compiled listing 
isn't available. Using this command, you 
can view source files on disk and disk files 
containing compiled listings without leaving 
the debugger. 
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Displaying Useful Information 


Whenever control is returned to the debugger 
(that is, after a single-step operation, or 
when a break point is encountered), it 
displays various information if it is 
desired. This information may include 
p-machine registers, the current  p-code 
operator, the information in the current 
markstack, or any specified memory location. 
In order to select what is displayed, the 
E(nable mode should be used. After entering 
'E', the following options are available at 
the command level, Register, P(code, 
M(arkstack, A(ddress, and E(very (all of the 
preceding). Any or all of these options may 
be enabled at the same time. 


If R(egister is enabled, a line is displayed 
after each single step. The following line 
is an example of that display. 





If P(code is enabled, a line such as the 
following is displayed after each step: 





If Mcarkstack is enabled, a line like the 
following is displayed after each step: 





Debugging and Analysis 


If A(ddress is enabled, the system generates 
a display like the following line. 





To initialize this address to a given value, 
use A(ddress mode at the outer level. Press 
A(ddress and the system displays’ the 
following prompt. 





Enter the absolute address in hexadecimal. 
The system displays eight bytes starting at 
that address. Also, that address is now 
displayed if the E(nable A(ddress option is 
on. 


Enabling E(very causes all of the above 
options to be enabled. 


The D(isable mode disables any of the 
options just described. The L(ist mode 
lists any of the above options. 
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Disassembling P-—Code 


At the debugger's outer level, there is a 
p-code option that displays the p-code 
mnemonics for selected portions of code. 
This option asks for: 





The indicated portion of code is’ then 
disassembled. This may be useful during 
Single-step mode if you wish to look ahead 
in the p-code stream. This mode may be 
exited before it reaches the ending offset 
by pressing <break>; control returns to the 
debugger. 


Performance Monitor Interaction 


The ‘'I' command calls the PM Interactive 
procedure within the operating system if the 
performance monitor is enabled. You may, in 
this way, gain access to various sorts of 
program performance information while using 
the Debugger. For more information, see the 
"Performance Monitor" section later in this 
chapter. 
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The 'Z' Command 


The '‘'Z‘' command displays the segment 
reference list for each segment which is 
currently associated (within the operating 
system as well as within the program being 
executed). This segment reference list is 
extracted from the environment vector (which 
is described in the Internal Architecture 
Reference Manual). 


Segments within the currently executing 
program, and within the operating system, 
may contain external references; that is, 
they may call routines from another segment 
or access variables from another segment. 
For each segment which has external 
references, a list of the referenced 
segments is given by the 'Z' command. The 
names of the referenced segments as well as 
the associated segment numbers are given. 
(When two or more segments reference a 
particular segment, the number associated 
with the referenced segment may vary among 
them. This segment number is used in the 
p-code operators which call external 
routines and access external variables.) 


9-15 


Debugging and Analysis 


For example, if you use the 'Z' command when 
the Debugger is called from the Command 
menu, the segment reference list for each 
unit within the operating system is 
displayed. Here is a partial listing: 


the sib is GOTOXY - 
A" KERNEL. Ss i eS 
£27) 2: GOTOXY- 5 
' 3 SCREENOP 


' the sib is DEBUGGER. ~~ 
4 KERNEL raga 
‘DEBUGGER © 
PDEBUGIN ~ 

EXTRALEX- 

EXTRAIO- .- 

-GOTOXY 

FILEOPS 

‘STRINGOP. . 
PASCALIO. 
-EXTRAHEA 


ADWONOUFN = 


a ae) 


the sib is PDEBUGIN: 
4 KERNEL “a2 
_* 2. PDEBUGIN. 


- the sib is SCREENOP | - 
KERNEL. ee Es 
-SCREENOP = 
SEGSCINI 

STRINGOP: | 
SEGSCPRO 

: PASCALIO. ~ 

EXTRAIO. 
SEGSCCHE - 

GOTOXY. 


WONAUERWN 


The "sib" is the Segment Information Block 
(which is described in the Internal 
Architecture Reference Manual). After 
"the sib is," the name of an associated 
segment is given. Below this name are the 
segments it references along with the 
associated segment numbers. 
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Example of Debugger Usage 


Suppose the following program is to be 
debugged: 





First we enter the debugger and set a break 
point at the beginning of the IF statement: 





After setting the break point we enable 
p-code (EP) and resume (R). Now we execute 
the program above, and when it reaches 
offset 6, the debugger is entered. We 
single-step twice: 





We see that our first single-step did a 
short load global 1. 
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NOTE: This put 'K' on the stack. 'K' ais 
NOT global 3; 'I' is global 3, 'J' is global 
2, and 'K' is global 1. Every string of 
variables (such as 'I', 'J', ‘'‘K' in a 
declaration) is allocated in reverse order. 
Boolean Bl, which follows, is at offset 5, 
and B2 is at offset 4. Parameters, on the 
other hand, ARE allocated in the order in 
which they appear. 


The second single-step did a short load 
constant 1 onto the stack. Now we are about 
to do an integer comparison ( <> ). Buc 
this is where our error shows up, so we 
decide to look at what is on the stack 
before doing this comparison: 





We list the registers and then look at the 
memory address to which register sp points. 
We discover a 1 on top of the stack (01 OO: 
this is a least-significant-byte-first 
machine) followed by a word of what appears 
to be garbage. This leads us to suspect 
that ‘'K' wasn't initialized. Looking over 
the listing, we quickly realize that this is 
the case. 


Debugging and Analysis 


Symbolic Debugging 


The symbolic debugging feature allows 
specification of variables by name, rather 
than p-code offset. Also, break points and 
portions of code to be disassembled may be 
indicated by procedure name and line number, 
rather than procedure number and p-code 
offset. 


Having a current compiled listing of the code 
in question is still essential for serious 
debugging efforts. 


To use symbolic debugging, it is necessary 
that the code being debugged is compiled with 
the $D+ option. The $D+ option, which 
defaults to $D-, instructs the compiler to 
output symbolic debugger information for those 
portions of a program that are compiled with 
$D+ turned on. 


Once a program is debugged, it should be 
recompiled without symbolic debugger 
information, because’ this information 
increases the size of the code file. Symbolic 
debugger information for a particular code 
segment is stored in another code segment. 
This other segment is given the same name as 
the code segment for which symbolic debugger 
information is generated. However, the name 
is in lowercase letters. (Executable code 
segments are always given names consisting of 
uppercase letters.) 
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Using symbolic debugging, break points may be 
specified by procedure name and line number 
for all statements covered by the $D+ option. 
The B(reakpoint command requests: 


Enter the first eight characters of the 
procedure name. The next line displayed is: 





The underlines actually are values that define 
the range of line numbers available to you 
within the specified procedure. (These line 
numbers appear on compiled listings.) Enter 
the desired line number for the break point. 


Variables within a given routine may be 
specified by name (rather than data segment 
offset number) if at least one statement 
within that routine is compiled with $D+. The 
V(ar command allows specification of G(lobal, 
L(ocal, I(ntermediate, or P(rocedure variables 
in this manner. E(xtended variables aren't 
allowed to be specified symbolically. The 
V(ar command prompts: 
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You may enter the first eight characters of 
the declared identifier. A line similar to 
the following appears: 





The segment is INIT; the procedure is 
FILL TABLES; and the variable is TABLE1. 


Similarly, the code to be disassembled by the 
p-code command can be specified symbolically 
for all portions of code covered by the $D+ 
option. This command requests: 


Enter the first eight characters of the 
procedure name. The system displays the 
following prompt: End Line#? 





The underlines are actually the boundaries 
that are available to you. You should enter 
the desired starting and ending line numbers. 
The specified code is then disassembled. 
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Symbolic Debugging Example 


To use symbolic debugging, some part of a 
Pascal compilation unit must be compiled 
with the {$D+} compile-time directive. 
After this code has been generated, it is 
possible to reference variables and 
procedures by name rather than offset. The 
following example is a small Pascal program 
that has been compiled with the 'D' option. 
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The following listing is an example of a 
debug session. 





The first time the debugger is entered, the 
program example isn't in memory and hence 
the symbolic segment isn't in memory. 
However, a break point can still be set 
symbolically providing you know on which 
line number to stop. For the second break 
point, the symbolic segment is in memory; 
because of this, its first and last line 
numbers are given. 


Notice the variable ‘'D' was accessed 
symbolically, and its contents are 
displayed. 


If you try to access symbolically when the 
actual code segment is in memory and its 
symbolic segment counterpart isn't present, 
the system displays the error message 
‘symbolic seg not in mem’. Use the 'Z' 
command in the symbolic debugger to find out 
if symbolic information is available for a 
particular segment. 
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The ‘'Z' command (as described above) 
displays segment reference lists. For 
example, the following is a partial list for 
a program called EXAMPLE. The lowercase 
name ‘example’ is the segment produced by 
the compiler which contains the symbolic 
debugging information for '‘'EXAMPLE'. The 
existence of ‘example' indicates that 
symbolic debugging information is available 
for at least one procedure in segment 
EXAMPLE’. 
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Sumnary of the Commands 


A(ddress 


B(reakpoint 


SCet 


RCemove 


L(ist 


C(hain 


U(p 

DCown 

Iniet 
F(ile 


E(nable 


D(isable 


I¢nteract 


Displays a given address. 


Segment, procedure and offset 
must be specified. 


Allows a break point 
(O through 4) to be set. 


Allows a break point to be 
removed. 


Lists current break points. 


Changes frame of reference for 
V(ariable command. 


Chains up mark stack links. 
Chains down mark stack links. 
Lists current mark stacks. 
Allows viewing of text files. 


Fnables the following to be 
displayed. 


Disables the following from 
from being displayed. 


Interacts with the performance 
monitor. 
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L(ist 


R(egister 


P(code 
Mcarkstack 


A(ddress 


E( very 


Lists the following: 


The registers: mp, sp, erec, 
seg, lpc, tib, rdyq. 


Current p-code mnemonic. 
Mark stack display. 
A given address. 


All of the above. 


I(nteractive Interacts with the performance 


MCemory 
L(ock 
S(wap 


P(code 


Q(uit 


RCesume 


S(tep 


monitor. 


Memlocks the debugger. 
Memswaps the debugger. 


Dissassembles a given 
procedure. 


Quits the debugger, ‘'fresh' 
state if re-entered. 


Exits debugger, debugger 
remains active, ‘nonfresh'. 


Single steps p-code and returns 
to debugger. 


V(ariable 
G(lobal 
L¢ocal 
T(nter 


P(roc 


K(xtended 


Z(seg list 
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Displays global memory. 
Displays local memory. 
Displays intermediate memory. 


Displays data segement of given 
procedure. 


Displays variables in another 
segment. 


Displays segment lists. 
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PERFORMANCE MONITOR 


You can gain access to performance information 
by writing a unit called PERFOPS and including 
it in the operating system. This performance 
information can help you analyze application 
programs or the p-System itself. In the future, 
a full implementation of PERFOPS will be 
provided. Currently, however, only the hooks 
for a performance monitor are available. You 
should be aware that a_ sophisticated 
understanding of the p-System's internal 
architecture is required in order to write a 
useful performance monitor. 


The p-System expects the following interface for 
PERFOPS : 
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With the exception of PM Start Stop and 
PM Interactive, the operating system calls these 
procedures to indicate actions that the system 
is taking. Calls to these procedures by the 
operating system will only be made if the 
boolean, Has PM located in the KERNEL interface 
section, is set to true. (PM Start Stop is 
responsible for setting this boolean.) The 
following paragraphs describe the procedures: 


@ IM Fault. The operating system calls this 
procedure each time it enters the fault 
handler. (A fault occurs whenever a code 
segment is needed from disk, when the stack 
is about to run into the code pool or the 
heap, when the heap is about to run into the 
code pool or the stack, or if a pool fault 
occurs on systems with extended memory.) 
This procedure must not cause an additional 
fault; it must not call any procedure that 
may not be in memory. Stack space 
requirements must be minimized. 


@ (iM Dump Seg. The operating system calls this 
procedure from the fault handler. 
PM Dump Seg indicates that SegToDump is being 
removed from the code pool. (A SIB P is a 
pointer to a SIB. SIBs are described in the 
Internal Architecture Reference Manual.) This 
procedure must not cause an additional fault; 
it must not call any procedure that may not 
be in memory. Stack space requirements must 
be minimized. 


O-29 


Debugging and Analysis 


@ (Mw Prog Begin. The operating system calls 
this procedure to indicate that a program is 
about to start. 


@ (MM Prog End. The operating system calls this 
procedure to mark the end of a program. 


@ IM Start Stop. This entry point controls 
performance monitoring. This procedure 
should memlock PERFOPS and set Has PM to 
true, or vice versa depending on the value of 
parameter start. You must call this routine 
before PERFOPS can be used. It should be 
called again to deactive PERFOPS. It can be 
called directly from the program being 
analyzed. It could also be called from a 
small program executed just prior to (and 
just after) the program being analyzed. 


NOTE: PERFOPS must be memlocked before 
setting Has PM to true. 


@ IM Interactive. The ‘'I' command in the 
debugger calls this procedure if Has PM is 
true. This routine should provide data 


gathered by the first four procedures of 
PERFOPS. In this way, you can use PERFOPS 
interactively from the debugger. 
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Utilities 


INTRODUCTION 


The p-System's utilities are various precompiled 
programs that may assist you in many ways. Most 
of the utility programs included here are useful 
during program development. The utilities 
covered in this chapter are: 


The Decode utility which displays the content 
of code files in a meaningful fashion. 


The Native Code Generator which translates 
portions of a p-code file into 
processor-specific native code. 


The Patch utility which enables you to view 
the internal content of any sort of file. 


The XREF utility which is useful for 
analyzing Pascal programs. 
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DECODE 


The DECODE utility, called DECODE.CODE, provides 
access, in symbolic form, to all useful items 
contained in code files. The following 
information is available. 


@ Names, types, global data size, and other 
general information about all code segments 
in the file. 


@ Interface section text, if present, for all 
units in the file. 


@ Symbolic listing of any (or all) p-code 
procedures in any (or all) segments of the 
file. 


@ Segment references and linker directives 
associated with code Segments. 


The decoder should be used whenever you want 
detailed knowledge of the internal contents of a 
code file; for instance, an implementor of a 
p-machine emulator decodes test programs so that 
the object code can be executed and understood 
step-by-step. You should refer to the Internal 
Architecture Reference Manual, if detailed use 
of the decoder is planned. 


If a program uses a UNIT, the UNIT is decoded 
only if it is within the host file; DECODE won't 
search the disk for UNITs to decode. Assembly 
routines linked into a higher-level host won't 
be disassembled when the host is decoded. 
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When the system executes DECODE, the first 
prompt asks for the input code file (if 
necessary, the suffix .CODE is automatically 
appended). The next prompt asks for the name of 
a listing file to which DECODE's output may be 
written. This may be CONSOLE: (indicated by 
pressing <return>), REMOUT:, PRINTER:, or a disk 
file. The system then displays the following 
menu: 





The following items explain the DECODE options. 


D(ictionary Displays the code file's segment 
dictionary. 


AC1ll Disassembles all segments in the 
code file. 


#(dcet index A number of a dictionary index 
followed by <return> disassembles 
a given segment, if present. 


Q(uit Exits the decoder. 
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DECODE Programming Example 


Given the following Pascal program: 


{$LLIST1 TEXT} 


END. ; 


1 eeDeeios” 7% | 
ne Ae ~I:d.. 1°. PROGRAM DEMO; 
Sus 1rd 1. VARS OI: INTEGER; 
ae tid 
aps Vex 2 SEGMENT PROCEDURE ADDI; 
BeBe AS 130 0 BEGIN 
Cerne is | ANU Mea dS 3 ed 
L: Wo aed tb) 8 5 END. ea 
Ne ae eS 6 his aad gaa a 
10. 2  .1:0-- 0 BEGIN 
AT ae oes Oe ESS 05 
A220 ATS REPEAT 
MSs 22 a tee 4. ADDI; Heed Bites 
4% 208 eA 7 UNTIL - 1=400; 
Pos 1 ea 


oH 

WA 
‘ 

a eae 


DECODE displays a prompt asking for input and 
listing file names. Then, if you press 'D' to 
call the D(ictionary option, the system 
iol oa he the acridine a 


: INX. NAME - START SIZE. VERSION m TYPE SoH SEG_ TYPE RL FMY NAME - or. eoer 
ie ke . .. DSIZE SGRF. HISG. TS 
DEMO 2 20 Pauues 0 ” | PSEUDO a PROG | SEG R eee SS. 
ADDI -1 0 44° IV 0 = 50 PSEUDO. 3. ‘PROC SEG R_ . DEMO 
Ae ere = NO. SEG | oe: 
NO SEG 
NO SEG... 
“NO SEG~ 
/ .. NO SEG 
NO SEG ~ 
“ . tots (20 NOSES 
2 ee Tete 8, oe NO SEG 
Wr  -- St cet An “7. NO SEG 
WW: : PAM Reese gee | AE SNOLSEGSSs 
- ee Meta es aw te pee lg, tl NOAREGe 
13: Po ers es oe) ee IND REG ae) S 
Tee A Sy ket eg wee -NO SEG 
152 mp’ eet erarad . Rewer Ny hfe “NOL SEG 


i nag y | | ch is ba 8 


Sex: LEAST "significant byte + first 
. Next Page: ma 
Segment Guide: ACKL, Het: index, Deierionani atuit 
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The A(ll options produces the following 
disassembly. 


‘Constant pool for segment DEMO 
Block: a Block offset: 0 Seg offset: 0 


0: 1700 0000 445 4D4F. 2020 2020 0100 1400 0400 0000 see DENO = 
10: 0000 : at -- ? 


Block: 2° Block-offsec? 40. Sey ‘offsets. 40 
0: 0100 0000 oco0 | 


Segment: DEMO a Procedure: 1 


Block: 2 Block offset: 26 Seq-offset: 26 
Data size: © O Exist IC: 38 
Offset aa Hex .code 
0(000): — LpcB 50 8032 
~ 20002): ~ SRO 1 A501 
4(004):  SCXG ADDI — 1 ‘7201 © 
6(006) : SLDO sec (Sea 30 : 
» #(007):.: LDCI 400 * §19001 - 
10(OOA) : EFJ 4 D2F8 
exit code: . 
12(00C) : RPU . 0 “' 9600 
Constant pool for segment ADDI 
Block: aaa Block offset:. 0 Seg OTtsets Sue 
O: 1300 0000 46144 4449 2020 2020. 0100 4000 0400 0000 --==ADDI ~=== 


- 10: 0000 . -— 
(BLOG eS. 1 Block offset: 32 Seg offset: 32 


0: 0100 0000 Ocod 


Segment: ADDI Procedure: 4 ey 

Block: 1 Block-offset: 26 Seg offset: 26 . 

Data size: QO -Exist.IC: 30 
Offset yl ‘Hex code 
G(000): SLDbO 1 ‘aU, 
1(001) INCI . ED 
2(002): — SRO 1 A501 

exit code:. if 

4(004): RPU 0». - 9600 
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D(ictionary Display 


DECODE 's 


D(ictionary option display is a 


format of the code file segment dictionary. 
The following items describe the information 
that is displayed. 


Index 


Name 


start 


Size 


Version 


DECODES name for each segment; 
individual segments may be 
disassembled by entering their 
number and pressing <return>; for 
example, ‘O<return>' for this 
sample causes only DEMO to _ be 
disassembled. 


Contains the names of = each 
segment. 


Contains each segment's starting 
block (relative within the code 
file). 


The length in words of each 
Segment. 


The p-System version number of the 
segment. 


M TYPE is the machine type. Usually this is 


M PSEUDO, 


indicating a p-code segment, but 


assembled segments indicate a given machine. 
Other possible values for M TYPE are M 6809, 


M PDP, 


M 8080, MZ 80, MGA 440, M 6502, 


M 6800, M 9900, M 8086, and M 68000. 
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SEG TYPE can be NO SHG, PROG SEG, UNIT SEG, 
PROC_SEG, or SEPRT SEG. NO SHG is an empty 
segment slot, PROG SEG is a program segment, 
UNIT SEG is a UNIT segment, PROC SHG is a 
SEPARATE routine segment, and SEPRT SEG is an 
assembled segment. 


The RL columns indicate whether or not the 
segment is relocatable and whether it needs to 
be linked. An 'R' indicates a relocatable 
segment. An 'L' indicates a segment that must 
be linked. 


If the segment is declared within a program or 
unit, then the FMY NAME column contains its 
family name, that is, the name of the program 
or unit. Otherwise, the DSIZE SGRF 4HSG 
columns are displayed and contain, 
respectively, the compilation module's data 
Size, segment references, and the maximum 
number of segments. 


At the bottom of the screen, '[(C):' is 
followed by whatever copyright notice the code 
file may have. The next line indicates the 
byte sex of the code file. The menu is the 
last line on the screen. On the same line, 
the block number of the next portion of 
segment dictionary is displayed after "Next 
Page:". (In this example, the segment 
dictionary is entirely contained in block zero 
so next page is zero. The last portion of the 
segment dictionary always points back to block 
ZeETO. ) 
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Disassembled Listing 


The first portion of a disassembled listing 
Shows the housekeeping information at the 
beginning of a code segment. The block number 
of this information is given. (Code files 
start at block 0.) The block offset and 
segment offset are always 0. The information 
occupies the first 11 words (0 through 10) of 
the segment. This housekeeping information 
(which is described in the [Internal 
Architecture Reference Manual) includes such 
things as the segment name, byte sex indicator 
word, part number, and so forth. To the 
right, the same information is displayed as 
ASCII characters when printable, and as dashes 
when nonprintable. (The segment name is 
usually the most obvious part of this 
display.) 


The next few lines have the same format and 
display the constant pool. The block offset 
and segment offset are always nonzero for the 
constant pool. They represent the offset, in 
bytes, of the constant pool from the beginning 
of the block and the beginning of the segment, 
respectively. String constants and character 
type constants are usually easy to pick out in 
the ASCII display to the right. 
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The disassembled code itself is displayed by 
procedures. The block number, block offset, 
segment offset, data size, and Exit IC are 
displayed. (Data size and Exit IC are 
described in the Internal Architecture 
Reference Manual.) The OFFSET column shows the 
offset in bytes from the front of the 
procedure (the count is in both decimal and 
hexadecimal). Then the p-code mnemonic is 
displayed; followed by the operands, if any; 
and finally, the HEX CODE for that particular 
instruction. 


The OFFSET column corresponds to the fourth 
column in a compiled listing. 


Jump operands are displayed as offsets 
relative to the start of the procedure, rather 
than IPC-relative (IPC is the instruction 
program counter). This is to make the 
disassembly more readable. Thus, the operand 
shown is the offset of some line; in the 
example, the equal false jump (EFJ) on line 10 
shows 4, which means line 4—the SCXG 
instruction; the HEX CODE indicates that the 
offset is actually F8 (or -8), which is 
IPC-relative. 


If a single segment were to be disassembled 
(rather than using the A(11) command), a line 
similar to the following would be displayed. 
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Selecting A(ll) disassembles all of the 
procedures in the segment (in the example 
there is only one). Entering the number of a 
procedure followed by <return> disassembles 
that procedure. If present, L(inker 
information, S(egment references, and 
I(nterface text may also be displayed. 


For example, if the segment is a unit with 
interface text and you press 'I', the 
following listing may be displayed. 





If the segment had references to other 
segments and you press 'S', the following 
listing may be displayed. 





If the segment had linker information and you 
press 'L', the following listing may be 
displayed. 
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NATIVE CODE GENERATOR 


The Native Code Generator (NCG) is a utility 
program that translates selected portions of an 
executable p-code file into processor-—specific 
native code (n-code). Using native code 
directives inserted into the source code, you 
indicate which portions of the file are to be 
translated. The result of this procedure is an 
equivalent p-System code file that contains 
p-code and n-code. The NOG will translate only 
valid executable code files produced by a 
p-System compiler. 


Because n-code generally executes faster than 
p-code, the NCG can be used to speed up the 
execution of selected portions of p-code; for 
example, portions of code where most of the 
run-time is spent. However, p-code was designed 
for compactness and, consequently, takes up less 
space in memory than n-code. To use the NOG 
effectively, translate only those portions of 
p-code for which execution time is critical. 
Misuse of the NGG can greatly increase the size 
of the code file. 


You indicate what portions of code are to be 
translated by inserting native code directives 
into the source file before compilation. The 
following compile-time switches are the native 
code directives. 


$N+ and $N- 
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You insert the first switch S$N+} where the 
translation should begin and insert the last 
switch {$N-~} where the translation should end. 
When the compiler encounters the first switch, 
it begins generating the additional p—code 
necessary for n-code generation and stops 
generating when it encounters the last switch. 
The default setting for this compiler option is 
{$N-fT. (This notation applies to UCSD Pascal. 
Similar notations apply to other languages. ) 


Directives and Pascal 


Because the NGG translates a Pascal code file 
on a procedure—by—procedure basis, only a 
complete procedure (function or process as 
defined in UCSD Pascal) can be translated. 
One set of native code directives may 
designate more than one procedure; but the 
native code generation can't begin within the 
body of a procedure. The following example 
shows the use of the native code directives in 
Pascal. 
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The object code file, produced by the compiler 
from source code containing native code 
directives, is an executable p-code file that 
maintains its machine portability. The only 
difference is that the native code directives 
Slightly increase the size of the object code 
file. 
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Directives and BASIC 


The native code directives ($N+ and $N—) can 
be inserted into the BASIC source code file at 
any point within a procedure. You can specify 
translation on a statement-by-statement basis. 
The following example shows the use of native 
code directives in BASIC. 





Directives and FORTRAN 


To designate code for translation in a FORTRAN 
source code file, you must place the native 
code directive $NATIVE before the first 
statement function or executable statement in 
a procedure. The native code directive must 
begin in the first column of the line. The 
translation directive still applies for the 
entire procedure. The following example shows 
the use of native code directives in FORTRAN. 
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Running the NCG 


The NOG is run by executing the appropriate 
code file (such as Z80.NCG.CODE). 


The NCG generates a prompt asking you for an 
input code file and an output code file. The 
output file must contain the suffix .CODE . 
Only executable code files can be translated 
by the NOG (they must be already linked). 


The NCG will produce a formatted listing of 
the code generated for each procedure it 
translates. The NCG generates a prompt asking 
you for the name of a listing file. To 
produce a listing, enter a listing file name 
(for example, Console:, Printer:, #5:List, 
List.Text). To eliminate the listing, press 
<return> in response to the prompt. 
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The following listing 


1s an example of 


function MAX translated on the Z80 NCG., 


me ee ke a eS re “ee ee ree ew ee Se a 
BSS =] SS es ee en ee ee eee ee ee eS SS SS SSS 


procedure 2- 


Final Z80 Code for.segment TEST 


Segment offset 30. 
Source Object - 
P-Code-N-Code 
(Dec. Offsets). 


»RADIX- 


10 


me wm me ee a ee ee i ee ee ee ee ee we ee ee 
ee eee 


OVRUBRWNONF A OOO. 


ye 
: 2 | : 
+) 
oO 
m 
Oo 
O° 


- 26 |- F24B00. 


“9: 29) 210€00 
eC SB De 
33.] DDSEOC 


36 | DDS60D. 


*329-|.%3 
40) 2c 
ooh SAT f2 
Ws. 421635800 
13:- 45) 210€00 
48 | 09 


491 DDSEOA ~ 


52 | DD560B8 
." > | 73° ; 
6] 2c 
57 | 72 
Joe IY 38 | Cb4200 
15: 61 | 
61 | 9602 . 


- ,P-code 


Ls. 


= 2: 


L3:° 


L4: 


exit de. 


zp7code 
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RPU- 


91,,-30 


EB, CIX#10) 


D, CIX+11) 
L,CIX+12) 
H, (IX+13) 


-E, CIX#12)- 


D, CIX+13) 


(HL), E 


L 
CHL): ,D 
L4 

HL 14 


HL, BC 
-E, C1X+10) 


D, CIX+11) 
CHL) E 

L 

CHL) ,D 


-INTRP_REL+66 


2 
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The following listing is an example of 
function MAX translated on the 8086, 
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The following listing is an example of 
function MAX translated on the 8080. 


EE EE EE Se a ee ee Se ey el Se st Ss 


SSS 8 a a a a a SS SF SS FS FF SS SS SSS SSS SSE 


“Final 8080 Code for segment TEST procedure 2 
Segment offset 30 


‘Source Object _ #RADIX 10 
P-Code N-Code ; 
(Dec. Offsets) Steals «EQU BC 
O| -WORD 96,-30 
0 2 
4: a A8 . yp-code NATIVE : 
1 | 210A00 LD- *.HL;10 
4) 09 | ADD HL,BC 
= els LD -E,CHL) 
6} 2c . INC - L 
7| 56 - LD D, CHL) 
8 | 210C00 LD HL,12 
11) 09 ADD HL,BC 
12] 7E LD A, CHL) 
13 | 2c INC L. 
14 | 66 “LD H, CHL) 
15 | 6F LD L,A 
16} 7A LD A,D 
17] AC XOR H 
18 | F23700 JP P,L1 
21} A2 AND D. 
22 | 33800 dP L2 
25) 7B . L1: LD A,E 
26 |.95 Jae SUB 7A 
27 | 7A LD  A,D 
28.) 9C A SBC Ae 
SEE 29 | F24F00 ee ek Lae. JP Se Pye 
Feta egy ee E00, Ae LB HL, 12 
35 | 09 a ADD ~ -HL,BC : 
SOx Ee canis he Sew, LD yd Pea 
A Ae a gre } PENG he ar Ho 
Sono tee = ES Sees ge ear | BP 
39-1 .210E00 - a ED: HEy14 + = 
42,09 . ek - ADO ~ - HL,BC 
43 | 735 VA ae LO: = = CHEE 
44)°2¢ ~ a ee INC Lk. 
3 45.072 le Ei eC HLS Bs: 
142: . 46) '¢35D00° or ade ran eae 
13:°- 49 |. 210A00 7 C320 5+ Lp HL,10 
S21 O92 FN os oe te asad ADD: HL,BC 
“33 '| 5€ ; LD” E, CHL) 
54°} 2c | SANE oe 
55°; 56- - Sob ce DS CHED 
=~ 56) 210800 .°-.' _- = et ADs =) HE hee 
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The following listing is an example of 
function MAX translated on the 9900. 
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The preceding listings show the hybrid mixture 
of p-code and n-code produced by the NCG. 
Cooperation between the n-code code and the 
p-machine emulator (PME) is achieved using the 
following conventions: 


@ NATIVE is the p-code that instructs the PME 
to start executing n-code. On the Z80, 
8080, and 8086, execution starts on the 
byte following the NATIVE instruction. On 
the 9900, execution begins on the first 
word boundary following the NATIVE 
instruction. 


@ The header lists the register conventions: 
p-machine registers on the left and 
processor registers on the right. 


@ The following reference points on _ each 
processor listing indicate the instruction 
that returns the processor from n-code to 
p-code. 


Z80 Listing, line [4 
8086 Listing, line L3 
8080 Listing, line 14 
9900 Listing, line L2 


@ On the Z80 and 8080, global and external 
variables are referenced through BASE 
relative relocation. On the 8086, glohal 
variables are referenced through register 
DX, which contains Base. On the 9900, 
global variables are referenced indexed 
from R14, which contains Base. On both the 
8086 and the 9900, external variables are 
referenced via base relative relocation. 


6-23 


Utilities 


On the whole, the listing looks very much like 
a listing created by the assembler. The 
following notes may help interpret the 
differences. 


@ P-code is preceded by the the notation: 
;p-code (all other instructions are 
n—-code. ) 


@ The exit code point of the procedure is 
marked by the notation: j;exit code. 


@ The left-most colum of numbers contains 
decimal byte offsets of equivalent p-code 
in the original code file. These offsets 
Should help identify the source code by the 
offset in the compiler listing. 


@ The second colum contains decimal byte 
offsets into the final procedure code 
generated by the NCG. 


NCG LIMITS 


The NOG produces an object code file whose 
execution behavior is identical to the p-—code 
file, except for differences in execution 
speed. 


In those instances in which the compiler emits 
calls to a run-time support routine, the NGG 
leaves the p-code intact. Therefore, p-—code 
is used in those places where translation 
would generate excessive code. 
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Sequences of straight n-code (code between a 
NATIVE instruction and its matching return 
instruction) are treated by the p-machine as a 
Single p-code. (See individual processor 
listings. ) This fact causes two problems. 
First, although the <break> key may be 
recognized by the p-machine emulator (PME) at 
any point, no further action is taken until 
the next p-code boundary (that is, until the 
current p-code is completed and the next 
p-code is encountered). Since there are no 
p-code boundaries in n-code, long sequences of 
n-code can't be terminated by pressing the 
<preak> key. second, p-machine events 
(interrupts), like the break key, are only 
acted upon at p-code boundaries. 


It is possible to work around these problems. 
You may force a p-code procedure call by 
calling an empty procedure. P-—code operators 
which perform procedure calls’ aren't 
translated into n-code. Therefore, long 
sequences of n-code can be broken into smaller 
sequences by a procedure call. Since it is 
the procedure call itself that breaks up the 
sequence, the called procedure could be an 
empty shell. 
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Some unusual FORTRAN and Pascal contructs 
create code that the NOG won't translate. For 
example, uSing the Pascal primitive, 
P Machine, to generate an RPU instruction. 
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PATCH 


The Patch utility enables you to view files and 
alter them interactivley on the byte level. 


Patch is meant to be used interactively with a 
CRT. It uses the screen control module (see the 
Internal Architecture Reference Manual) to 
accomplish this; therefore, it is 
terminal—independent (within limitations). 


There are two main facilities in Patch: a mode 
for editing files on the byte level and a mode 
for dumping files in various formats. 


The byte-editing capability allows you to edit 
text files, make quick fixes to code files, and 
create specialized test data. 


The dump capability provides formatted dumps in 
various radices. It also allows dumps from main 
memory - 


EDIT Mode 


When the system executes Patch, you are in the 
EDIT mode. DUMP is reached by entering 'D'. 
No information is lost in chaining back and 
forth between the two modes. 


6-27 


Utilities 


EDIT allows you to open a file or device, read 
selected blocks (specified by relative block 
number) into an edit buffer, either view that 
buffer or modify it (with TYPE), and write the 
modified block back to the file. The system 
displays buffers on the screen in the desired 
format; these can be edited in a manner 
Similar to using the screen-—oriented editor. 


The following paragraphs describe the 
individual commands of the EDIT mode. When it 
1S impossible to perform a command, Patch 
responds with self-explanatory error messages. 
The following lines are the EDIT mode menu. 





The following items explain each menu option. 


DCump Calls DUMP. 

Gcet Opens the file or device and 
reads block zero into the 
buffer. 

R(ead Reads a specified block from 


the current file. 


S(ave Writes the contents of the 
buffer out to the current 
block. 
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M(ix 


Mixed 


Hex 


T(nformation 


F (orward 


B(ackward 


V(iew 
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Changes the display format 
for “the <<current. block. 
Pressing '‘'M' toggles to 
change from one format to 
another: hexadecimal or 
mixed. 


Displays printable ASCII 
characters and the 
hexadecimal equivalent of 
nonprintable characters. 


Displays the block in 
hexadecimal digits. 


Displays information about 
the current file including 
the file name, the file 
length, the number of the 
current block, whether the 
file is open, whether 
UNITREADS are allowed, the 
device number (-1 if UNITIO 
is false), and the byte sex 
of the current machine. 


Gets the next block in the 
file. 


Gets the preceding block in 
the file. 


Displays the current block 
(see M(ix). 
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W(ipe Clears the display of the 
block off the screen. 

Qcuit Quits the Patch program. 

T(ype Goes into the typing mode, 


which allows the buffer to 
be edited (described in 
following section). 


TYPE Mode 


The TYPE mode, like the screen-oriented 
editor, allows the information on the screen 
to be modified by moving the cursor and 
entering over existing information. TO 
correct errors made while using the TYPE mode, 
leave the EDIT mode without saving the file, 
read the block over, and try again. 


The following line is an example of the TYPE 
mode menu. 


me ITO AN EEE eOeRE anc Toy Tsts: - tt re 


“TYPE: Char, Hex, FCILL, Udp, DCown, Lteft, RUght, <vector arrows>, Qtuit 
C(haracter Exchanges bytes in the buffer 
for ASCII characters as they are 
pressed, starting from the 
cursor and continuing until you 


press <etx>. Only printable 
characters are accepted. 


6-30 


Utilities 


H(ex Exchanges bytes in the buffer 
for hexadecimal digits as they 
are pressed, starting from the 
cursor and continuing until a 
'Q@' is pressed; (hexadecimal 
digits can be either uppercase 
or lowercase). 


F(ill Fills a portion of the current 
block with the same _ byte 
pattern. Accepts either ASCII 
characters or hexadecimal digits 
for the pattern; upon 
completion, the cursor rests 
after the last byte filled. 


The following commands move the cursor around 
within the block of displayed data. The 
cursor is always at a particular byte. Rather 
than moving off the screen, the cursor wraps 
around from side to side and from top to 
bottom. 


U(p Moves the cursor up one row. 

D(own Moves the cursor down one 
YOW. 

L¢eeft Moves the cursor left one 
column. 

R(ight Moves the cursor right one 
column. 
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<vector arrows> Moves the cursor in the 
direction of the arrow. 


Qcuit Exits the TYPE mode and 
returns to the EDIT mode. 


DUMP Mode 


You can generate DUMP mode in the following 
formats: 


@ Decimal, hexadecimal, and octal words. 
@ ASCII characters, if printable. 


@ Decimal (BCD) and octal bytes. 


DUMP can flip the bytes in a word before 
displaying it or simultaneously display a line 
of words in both flipped and nonflipped form. 


Input to the DUMP mode can be a disk file you 
specify or can come directly from main memory. 
(The DUMP mode is used primarily to examine 
the PME and/or the Basic Input/Output 
Subsystem [BIOS]. ) 


The width of the output can be controlled; a 
line may contain any number of machine words: 
15 words fill an 132-character line, and 9 
words fill an 80-character line. 
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When you enter the DUMP mode, the screen 
displays two options: D(o and Qquit. Also a 
lengthy set of format specifications are 
displayed. These can be modified by pressing 
the letter of the item and then entering the 
specification. To activate the specification, 
press 'D' for D(o. 


The following list shows the DUMP mode 
specifications: 


a. The input: A disk file or device. 

b. The number of the block from which dumping 
starts; if (A) is a device, this number 
isn't range—checked. 

c. The number of blocks to print out; if this 
is too large, DUMP merely stops when there 
are no more blocks to output. 

d. Pressing 'D' starts the dump. 

e. A toggle: If true, it reads from main 
memory; if false, it reads from the file in 
(A). 

f. An offset: The dump may start with a byte 
that is past byte zero; O <= (F) <& 


maxint. 


ge. The number of bytes to. print, 
O <= (G) <= maxint. 


h. The output file, opened as a text file. 
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i. The width of the output line, in machine 
words; 1 <= (I) <= 15. 


The following six items have three associated 
Booleans that must be specified: USE, FLIP, 
and BOTH. 


USE tells DUMP whether or not to use the 
format associated with that item. 


FLIP tells DUMP whether or not to flip the 
bytes before displaying words in that 
format. 


BOTH tells DUMP to simultaneously display 
both flipped and nonflipped versions of the 
line. If BOTH is true, the value of FLIP 
doesn't matter. 


j- Display each word as a decimal integer. 


k. Display each word as hexadecimal digits in 
byte order. 


1. Display each word as ASCII characters in 
byte order; nonprintable characters are 
displayed as hexadecimal digits. 


m. Display each word as an octal integer; this 
is the octal equivalent of (J). 


n. Display each word as decimal bytes (BCD) in 
byte order. 
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Oo. Display each word as octal digits in byte 
order. 


S. Put a blank line after the nonflipped 
version of a line. 


t. Put blank lines between different formats 
of a line. 


Both the EDIT and DUMP modes remember all 
their pertinent information when the other 
mode 1S operating. 


Prompts 


All user-supplied numbers used by PATCH are 
read as strings and then converted to 
integers. Only the first five characters of 
the string are considered. If there are any 
nonnumeric characters in the string, the 
integer defaults to zero. If integer overflow 
occurs, the integer defaults to maxint. 
(Since integer overflow can only be detected 
by the presence of a negative number, integers 
in the range 65536 to 98303 come out modulo 
32768, ) 
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THE XREF UTILITY 
THE CROSS—REFERENCER 


Introduction 


The procedural cross—-referencer (XREF) is a 
software tool that helps you interpret large 


Pascal program listings. The referencer 
provides a compact summary of the procedure 
nesting in a program; a list of the 


procedures; and, for each, the procedures that 
call them; and a table of calls each procedure 
made along with all nonlocal variable 


references. It thus provides information 
about the interprocedural dependencies of a 
program. 


Referencer's Output 


The referencer produces five tables and an 
_ optional warnings file: 


/ @ lexical structure table: summarizes static 
procedure nesting. 


¥ @ Call structure table: lists procedures and 
- the procedures that they call. 
/e 


Procedure call table: presents procedures 
, and the procedures that call them. 


/@ Variable reference table: shows each 
procedure and the variables it references. 
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Y@ Variable call table: lists each variable 
and the procedures which reference or 
modify iC. 


@ Warnings file if desired: indicates 
possible problems in the source program. 


Lexical Structure Table 


The first table displays the lexical 
Structure and the procedure headings. (The 
term procedure means procedure, function, 
process or program in this document unless 
otherwise stated.) As the system reads the 
input program, it prints out each heading 
with the line numbers of the lines in which 
it occurs. The text is indented to display 
the lexical nesting. (This indentation must 
sometimes be compressed to fit on an output 
line.) 


Referencer considers a procedure heading to 
be any text between the words: procedure, 
function, process, or program—ard the 
semicolon which follows. This isn't the 
Pascal definition, but is more useful in 
debugging programs. If these reserved words 
are embedded within comments, they are 
ignored. 
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The Call Structure Table 


The system produces the second table after 
it scans the program completely. The call 
structure table is the result of examining 
the internal data. For each procedure 
listed in alphabetical order, the table 
holds: 


The line-—number of the line on which its 
heading starts. 


Unless it was external or formal (and had 
no corresponding block), the line number 
of the BEGIN that starts its statement 
part. 


The characters ‘ext’ if the procedure has 
an external body (declared with a 
directive other than FORWARD); the 
characters ‘fml’ if it is a formal 
procedural or functional parameter; or 
'eh?' =6if it is declared forward with no 
associated forward block or BEGIN. If a 
number appears, the procedure has been 
declared FORWARD and this is the line 
number of the line where the block of the 
procedure begins (that is, the second 
part of the two-part declaration). 
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@ A list of all user-declared procedures 
directly called by this procedure. (In 
other words, their call is contained in 
the statement part.) The list is in 
order of occurrence in the text; a 
procedure isn't listed more than once. 


@ A list of variables referenced by this 
procedure; and, if nonlocal, the 
procedure in which they were declared. 
If a variable is modified by an 
assignment, then it is printed with an 
asterisk ( * ) in front of it. 


The Procedure Call Table 


This table is an alphabetical list of 
procedures ; and for each procedure’ the 
procedures that call it. 


Variable Reference Table 


This table is an alphabetical list of 
procedures; and, for each procedure, the 
variables that the procedure examines or 
modifies in any way. If the variable isn't 
local to the procedure in question, then the 
procedure is listed in which the variable 
was declared. 
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Variable references are shown in three 


forms: 
@ <variable name> ::= a local variable 
@ <procedure name> <variable name> ::= 


a variable defined in <procedure> that is 
used but not modified 


<procedure name>*<variable name> ::= 
a variable defined in <procedure> which 
is modified 


Variable Call Table 


The form of the variable call table is 
demonstrated in the following line. 





The first procedure name is the procedure 
that owns the variable name, and the 
following procedure(s) either examine or 
modify that variable. 
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Warnings File 


A file of warning messages. There are three 
types of warning messages in the warning 
file: 


@ '‘Symbol' may be undeclared line# xxxx. 


@ '‘'Symbol' may not be initialized line# 
xx. 


@ Not standard, nested comments line# xxxx. 


'Symbol' is an identifier, and xxxx is the 
number of the line on which it occurs. 


Referencer only catches initializations done 
by replacement statements (':="'), SO 
variables that are initialized by procedure 
calls (including READ, and so on) are 
flagged as possibly uninitialized. 
Depending on the program, there may be a 
surplus of such warning messages. 


The ‘Not standard, nested comments’ warning 
refers to the nesting of comments having 
different bracket types: (* Jike this 
{ verstehen Sie? } *), which is accepted by 
the UCSD Pascal compiler, but not’ the 
current ISO draft standard. 


The warnings file may only be generated if 
the variable reference table is also 
generated. 
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Using Referencer 


The referencer has options that are 
user-defined at run-time. When you X(ecute 
XREF, referencer displays prompts asking for 
answers for the following questions. 


@ Width of the output device? [40..132] 


This is the length of the output line for 
the available terminal/printer. 
Suggested output width is 80 characters. 


@ File to be Cross—Referenced? 


The name of the text file that contains 


the Pascal program to be referenced. If 
the specified file can't be successfully 
opened, the prompt is repeated until you 
enter a valid input file name or press 
<return>. Entering an empty file name, 
(<return>) exits referencer. 
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n}: 


@ Is this a compiled listing? 


The program reads either .TEXT files 
containing Pascal source programs or 












Using a compiled listing as input assures 
you that the line numbers referenced are 
synchronized with the line numbers the 
compiler generates. 


@ Do you want intrinsics listed? 


This allows identifiers such as 
'WRITELN', ‘'PRED', and '‘GET' to. be 
accepted as valid symbols. These are 
then cross-referenced as procedures 
listed outside the lexical nesting and, 
therefore, aren't expected to have a 
'BEGIN' associated with them. 


@ Do you want initial procedure nestings? 


This generates the lexical structure 
table. This table shows the procedure 
headings and, for each procedure, the 
list of procedures that it calls. 


@ Do you want procedure called by trees? 


This option is offered only if the 
lexical structure table is desired. A 
'y' generates both the call structure 
table and the procedure call table. The 
procedure call table lists each procedure 
and all of the procedures that call it. 
(A warning is displayed if less than 
10,000 words of memory are available to 
generate these trees; no provision is 
made for possible stack overflow.) 
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@ Do you want variables referenced? [y/n]: 


A 'y' generates the variable reference 
table. 


@ Do you want variable called by trees? 
[y/n]: 


A 'y' generates the variable call table. 
@ Do you wish warnings? [y/n]: 


'Y' generates the warnings file. This 
option is offered only if the preceding 
selection was made. 


@ Please enter the name of the warning 
file: 


If you select warnings, then you heve the 
option of directing the warnings to any 
file. If the file is a disk file, the 
name should have '.TEXT' appended to it. 


@® Output File: 


The name of the file to which you would 
like the output directed. If the file is 
a disk file, the name should have '.TEXT' 
appended to it. 
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The referencer expects to read a complete 
and syntactically correct Pascal program. 
Although results with syntactically 
incorrect programs aren't assured, the 
referencer isn't sensitive to most flaws. 
It cares about procedure, function, program 
headings, and about properly matching BEGINs 
and CASEs with ENDs in the statement parts. 


Referencer doesn't try to format procedure 
and function headings; it leaves them as 
they were entered in the program, except for 
aligning indentations. 


The tables are all as wide as the output 
line length, as specified by you. Kighty 
characters are usually sufficient. For 
large programs, the first table (the lexical 
structure table) is clearer with a larger 
print line. 


Limitations 


When presented with incorrect Pascal 
programs, the hehavior of referencer isn't 
assured. However, it has been designed to 
be reliable, and there are few flaws that 
can cause it to fail. The most critical 
features are: (1) the general structure of 
procedure headings; and (2) correctly 
matching an END with each BEGIN or CASE in 
each statement part (Since this information 
is used to detect the end of a procedure). 
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If an error is explicitly detected 
(referencer has very few explicit error 
checks and minimal error-recovery), the 
system displays the following message: 





The line number displayed (##*) is the line 
where the program found an error; like all 
diagnoses this doesn't assure that the 
correct reason is ascribed to the error. 
Processing continues for a while despite the 
fatal error, but only the lexical structure 
table is produced. 


Referencer accepts standard Pascal programs, 
UCSD Pascal programs, and p-System-units; it 
processes each correctly. 
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APPENDIX A 
EXECUTION ERRORS 


Fatal system error 

Invalid index, value out of range 
No segment, bad code file 
Procedure not present at exit time 
Stack overflow 

Integer overflow 

Divide by zero 

Invalid memory reference <bus timed out> 
User break 

Fatal system I/O error 

10 User I/O error 

11 Unimplemented instruction 

12 =6Floating point math error 

1 String too long 

14 Halt, Break Point 

15 Bad Block 

16 Break Point 

17 Incompatible Real Number Size 

18 Set Too Large 

19 Segment Too Large 


DOAN GQ ahwnNrO 


All run-time errors cause the system to 
I(nitialize itself; FATAL errors cause the 
system to rebootstrap. Some FATAL errors leave 
the system in an irreparable state, in which 
case you must rebootstrap. 
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1/O RESULTS 


No error 

Bad Block, Parity error (CRC) 

Bad Device Number 

Illegal I/O request 

Data-com timeout 

Volume is no longer on-line 

File 1S no longer in directory 

Bad file name 

No room, insufficient space on volume 

No such volume on-line 

No such file on volume 

Duplicate directory entry 

Not closed: attempt to open an open file 
Not open: attempt to access a closed file 
Bad format: error in reading real or integer 
Ring buffer overflow 

Volume is write-protected 

Illegal block number 

Illegal buffer 
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DEVICE NUMBERS 


Device Volume 
Number Name 


CONSOLE: 

SYSTERM: 

<System disk '*'> 
<other disk> 
PRINTER: 

REMIN: 

REMOUT : 

02 lL 27 <additional disks, 
subsidiary volumes, 
or user-defined 
serial devices> 

128...255 <user-—defined devices> 
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000 
001 
002 
003 
004 
005 
006 
007 
010 
011 
012 
013 
014 
015 
O16 
017 
020 
024 
O22 
023 
024 
025 
026 
027 
030 
031 
032 
033 
034 
035 
036 
037 


NUL 
SOH 
STX 
ETX 
EOT 
ENQ 
ACK 
BEL 
BS 
HT 
LF 
VT 
FF 
CR 
SO 
SI 
DLE 
DC1 
pc2 
DC3 
Dc4 
NAK 
SYN 
ETB 
CAN 
EM 
SUB 
ESC 
FS 
GS 
RS 
US 
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ASCII TABLE 
040 20 sP 64 
041 21 | 65 
042 22 " 66 
043 23 4 67 
044 24 $ 78 
045 25 4% 69 
046 26 & 70 
047 27 ' 71 
050 28 ¢ 72 
051 29 ) 73 
O52 2A * 74 
053 28 + 75 
054 2c , 76 
055 2D - 77 
056 2— . 78 
O57 2F / 79 
060 30 0 80 
061 31 1 81 
062 32 2 82 
063 33 3 83 
064 34 4 84 
065 35 5 85 
066 36 6 86 
067 37 7 87 
070 38 8 89 
07139 9 89 
072 3A: 90 
073 3B CS; 91 
074 3c < 92 
075 3D = 93 
076 3E > 94 
077 3F 2 95 


A-6 


100 
101 
102 
103 
104 
105 
106 
107 
110 
111 
112 
143 
114 
175 
116 
117 
120 
121 
122 
123 
124 
125 
126 
127 
130 
131 
132 
133 
134 
135 
136 
137 
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108 
109 
110 


112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 
127 


140 
141 

142 
143 
144 
145 
146 
147 
150 
151 

152 
153 
154 
155 
156 
157 
160 
161 
162 
163 
164 
165 
166 
167 
170 
171 

172 
173 
174 
175 
176 
177 
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APPENDIX E 
PASCAL SYNTAX ERRORS 


Error in simple type 
Identifier expected 
Unimplemented error 

')' expected 

':' expected 

Tllegal symbol (terminator expected) 
Error in parameter list 
'OF' expected 

'C' expected 

Error in type 

‘Tl’ expected 

']' expected 

"END' expected 

';' expected 

Integer expected 

'=' expected 

'BEGIN' expected 

Error in declaration part 
Error in <field-list> 

'.' expected 

'*' expected 

"INTERFACE' expected 
'TMPLEMENTATION' expected 
'UNIT' expected 


Error in constant 

":="' expected 

'THEN' expected 

'UNTIL' expected 

'DO' expected 

'TO' or 'DOWNTO' expected in for statement 
'ITF' expected 

'FILE' expected 

Error in <factor> (bad expression ) 

Error in variable 
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101: 
102: 
103: 
104: 
105: 
106: 
107: 
108: 
109: 
: <tagfield> type must be scalar or subrange 
111: 
112: 
113: 
114: 
115: 
116: 


117: 
118: 


119: 
120: 


121: 
122: 


123: 
1234: 
125: 


Must be of type 'SEMAPHORE' 

Must be of type 'PROCESSID' 

Process not allowed at this nesting level 
Only main task may start processes 


Identifier declared twice 

Low bound exceeds high bound 

Identifier is not of the appropriate class 
Undeclared identifier 

Sign not allowed 

Number expected 

Incompatible subrange types 

File not allowed here 

Type must not be real 


Incompatible with <tagfield> part 

Index type must not be real 

Index type must be a scalar or subrange 

Base type must not be real 

Base type must be a scalar or a subrange 

Error in type of standard procedure 
parameter 

Unsatisified forward reference 

Forward reference type identifier in 
variable declaration 

Respecified parameters not OK for a 
forward declared procedure 

Function result type must be scalar, 
subrange or pointer 

File value parameter not allowed 

A forward declared function's result type 
cannot be respecified 

Missing result type in function declaration 

F-format for reals only 

Error in type of standard procedure 
parameter 
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126: Number of parameters does not agree 
with declaration 

127: Illegal parameter substitution 

128: Result type does not agree with declaration 

129: Type conflict of operands 

130: Expression is not of set type 

131: Tests on equality allowed only 

132: Strict inclusion not allowed 

133: File comparison not allowed 

134: Illegal type of operand(s) 

135: Type of operand must be Boolean 

136: Set element type must be scalar or subrange 

137: Set element types must be compatible 

138: Type of variable is not array 

139: Index type is not compatible with the 
declaration 

140: Type of variable is not record 

141: Type of variable must he file or pointer 

142: Illegal parameter solution 

143: Illegal type of loop control variable 

144: Illegal type of expression 

145: Type conflict 

146: Assignment of files not allowed 

147: Label type incompatible with selecting 
expression 

148: Subrange bounds must be scalar 

149: Index type must be integer 


190: Assignment to standard function is not 
allowed 

151: Assignment to formal function is not allowed 

152: No such field in this record 

153: Type error in read 

154: Actual parameter must be a variable 

155: Control variable cannot be formal or nonlocal 

156: Multidefined case label 

157: Too many cases in case statement 

158: No such variant in this record 

159: Real or string tagfields not allowed 
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160: 
161: 
162: 
163: 
164: 


165: 
166: 
167: 
168: 
169: 
170: 
L71: 
172: 
173: 
174: 
175: 
176: 


182: 
183: 


184: 
1&5: 


186: 
: Attempt to open library unsuccessful 
188: 


189: 
190: 
191: 
192: 
193: 
194: 
195: 


Previous declaration was not forward 

Again forward declared 

Parameter size must be constant 

Missing variant in declaration 

Substitution of standard proc/func not 
allowed 

Multidefined label 

Multideclared label 

Undeclared label 

Undefined label 

Error in base set 

Value parameter expected 

Value parameter expected 

Undeclared external file 

FORTRAN procedure or function expected 

Pascal functon or procedure expected 

Semaphore value parameter not allowed 

Undefined forward procedure or function 


Nested UNITs not allowed 

External declaration not allowed at this 
nesting level 

External declaration not allowed in 
INTERFACE section 

Segment declaration not allowed in 
INTERFACE section 

Labels not allowed in INTERFACE section 


UNIT not declared in previous uses 
declaration 

'USES' not allowed at this nesting level 

UNIT not in library 

Forward declaration was not segment 

Forward declaration was segment 

Not enough room for this operation 

Flag must be declared at top of program 

Unit not importable 
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201: Error in real number - digit expected 

202: String constant must not exceed source line 

203: Integer constant exceeds range 

204: 8 or 9 in octal number 

200: Too many scopes of nested identifiers 

201: Too many nested procedures or functions 

202: Too many forward references of procedure 
entries 

203: Procedure too long 

204: Too many long constants in this procedure 

206: Too many external references 

2o/’: Too many externals 

208: Too many local files 

259: Expression too complicated 


300: Division by zero 

301: No case provided for this value 

302: Index expression out of hounds 

303: Value to be assigned is out of bounds 
304: Element expression out of range 

398: Implementation restriction 

399: Implementation restriction 


400: Illegal character in text 
401: Unexpected end of input 
402: Error in writing code file, not enough room 
403: Error in reading include file 
404: Error in writing list file, not enough room 
405: 'PROGRAM' or 'UNIT' expected 
406: Include file not legal 
407: Include file nesting limit exceeded 
408: INTERFACE section not contained in one 
file 
409: Unit name reserved for system 
410: Disk error 


500: Assembler error 
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COMPILER BACK—END ERRORS 


The compiler back-end errors can result from a 
variety of problems. Basically, they occur when 
the back-end finds itself or the intermediate code 
file in an unexpected state. (The intermediate 
code file is a file used by the compiler to 
communicate between the front-end and back-end of 
the compiler. It consists of compiler directives 
intermixed with actual p-code.) Back-end errors 
can be caused by a corrupt intermediate code file, 
external forces (such as bad blocks on the disk), 
or source file information that is skipped by the 
front-end but used by the back-end. 


The following table lists each of the back-end 
errors and gives a possible explanation for their 
occurrence: 


Error 
Number Comments 


—1 While trying to generate the constant 
pool information for a particular code 
segment, the back-end tries to read 
one block from the intermediate code 
file and the read fails. 


id If the lexical procedure nesting is 
greater than 31, this error will 
occur. Since the front-end only 
allows nesting of seven procedures, 
this error should theoretically never 
occur. 
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The intermediate code file directives 
are bytes with values greater than 
202. If the back-end reads a 
directive with a value that is less 
than 253, error number 4 will result. 


The current procedure number is 
greater than the maximum number of 
procedures for that segment. 


The operator (variable, constant, jump 
location) that the back-end is trying 
to remap isn't in the scope of the 
compilation unit. 


The back-end can't find the target 
Site to jump to while resolving jumps. 


There are more than 400 jumps in the 
jump table while trying to enter a 
Site jump error. Try dividing each 
procedure with many jumps into more 
than one procedure. 


There are more than 400 jumps in the 
jump table while trying to enter a 
target jump. Try dividing each 
procedure with many jumps into more 
than one procedure. 


The code pointer is less than O or 
greater than the length of the 
intermediate code file while building 
a jump table. 
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22, 


23 


24 


20 


27 


28 


29 


A jump site can't be found in the jump 
table. 


Unexpected end of input while 
generating the LCO p-code instruction. 


Unexpected end of input’ while 
generating the LDC p-code instruction. 


The exit for a certain procedure can't 
be found in the jump table. 


The code pointer is less than O or 
greater than the length of the 
intermediate code file while 
generating p—code. 


The code pointer is less than O before 
trying to read in more code from the 
intermediate code file to the code 
buffer. 


The code pointer is less than O after 
trying to read in more code from the 
intermediate code file to the code 
buffer. . 


The current final output block number 
is greater than the block number of 
the intermediate code file being 
processed. 
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30 


31 


41 


36 
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The final code file size exceeds the 
intermediate code file size before 
trying to write more final code. 


The final code file size exceeds the 
intermediate code file size after 
writing more final code. 


The line length of a compiled listing 
exceeds 120 characters. (Note: This 
error can occur on a pre-IV.1 compiler 
if there is an illegal character after 
a DLE character.) 


Couldn't find a particular segment in 
the intermediate code file. 


The number of procedures doesn't match 
the number specified in the procedure 
dictionary. 


When you encounter a back-end error: 


@ If a syntax error has occurred in the front-end 
and a back-end error occurs, fix the syntax 
error and try recompiling. 


@ If there are bad blocks on any of the disks 
being used for the compilation replace the bad 
disks with good ones and try recompiling. 
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